/contrib/tcsh/tcsh.man
Unknown | 5380 lines | 5380 code | 0 blank | 0 comment | 0 complexity | 4a9554cf24153eeee47c6bd56146c920 MD5 | raw file
Possible License(s): MPL-2.0-no-copyleft-exception, BSD-3-Clause, LGPL-2.0, LGPL-2.1, BSD-2-Clause, 0BSD, JSON, AGPL-1.0, GPL-2.0
- .\" Copyright (c) 1980, 1990, 1993
- .\" The Regents of the University of California. All rights reserved.
- .\"
- .\" Redistribution and use in source and binary forms, with or without
- .\" modification, are permitted provided that the following conditions
- .\" are met:
- .\" 1. Redistributions of source code must retain the above copyright
- .\" notice, this list of conditions and the following disclaimer.
- .\" 2. Redistributions in binary form must reproduce the above copyright
- .\" notice, this list of conditions and the following disclaimer in the
- .\" documentation and/or other materials provided with the distribution.
- .\" 3. Neither the name of the University nor the names of its contributors
- .\" may be used to endorse or promote products derived from this software
- .\" without specific prior written permission.
- .\"
- .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
- .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
- .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
- .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
- .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
- .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
- .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- .\" SUCH DAMAGE.
- .\"
- .\" Style notes for the tcsh man page:
- .\"
- .\" - Tags in lists are bold, except in the FILES section where they are
- .\" italic.
- .\"
- .\" - References are bold for section headings and environment and shell
- .\" variables and italic for commands (externals, builtins, aliases, and
- .\" editor commands) and arguments to commands.
- .\"
- .\" - Be careful with the .B and .I macros: they handle only a limited number
- .\" of words. Work around this with \fB and \fI, but only if absolutely
- .\" necessary, because tcsh.man2html uses .B/.I to find name anchors.
- .\"
- .\" - Indent in multiples of 4, usually 8.
- .\"
- .\" - Use `', not '' or "", except of course in shell syntax examples.
- .\" '' at the beginning of a line will vanish!
- .\"
- .\" - Use \-, not -.
- .\"
- .\" - Include the tilde when naming dot files. `~/.login', not `.login'.
- .\"
- .\" - Refer to external commands in man page format, e.g., `csh(1)'. However,
- .\" tcsh is `tcsh', not `tcsh(1)', because this is the tcsh man page (and
- .\" see the next note anyway).
- .\"
- .\" - Say `the shell', not `tcsh', unless distinguishing between tcsh and csh.
- .\"
- .\" - Say `shell variable'/`environment variable' instead of `variable'
- .\" and `builtin command'/`editor command' instead of `builtin' or `command'
- .\" unless the distinction is absolutely clear from context.
- .\"
- .\" - Use the simple present tense. `The shell uses', not `The shell will use'.
- .\"
- .\" - IMPORTANT: Cross-reference as much as possible. Commands, variables,
- .\" etc. in the reference section should be mentioned in the appropriate
- .\" descriptive section, or at least in the reference-section description
- .\" of another command (or whatever) which is mentioned in a description
- .\" section. Remember to note OS-specific things in "OS variant support",
- .\" new features in NEW FEATURES and referenced external commands in SEE
- .\" ALSO.
- .\"
- .\" - tcsh.man2html depends heavily on the specific nroff commands used in the
- .\" man page when the script was written. Please stick closely to the style
- .\" used here if you can. In particular, please don't use nroff commands
- .\" which aren't already used herein.
- .\"
- .TH TCSH 1 "14 February 2012" "Astron 6.18.01"
- .SH NAME
- tcsh \- C shell with file name completion and command line editing
- .SH SYNOPSIS
- .B tcsh \fR[\fB\-bcdefFimnqstvVxX\fR] [\fB\-Dname\fR[\fB=value\fR]] [arg ...]
- .br
- .B tcsh \-l
- .SH DESCRIPTION
- \fItcsh\fR is an enhanced but completely compatible version of the Berkeley
- UNIX C shell, \fIcsh\fR(1).
- It is a command language interpreter usable both as an interactive login
- shell and a shell script command processor.
- It includes a command-line editor (see \fBThe command-line editor\fR),
- programmable word completion (see \fBCompletion and listing\fR),
- spelling correction (see \fBSpelling correction\fR),
- a history mechanism (see \fBHistory substitution\fR),
- job control (see \fBJobs\fR)
- and a C-like syntax.
- The \fBNEW FEATURES\fR section describes major enhancements of \fItcsh\fR
- over \fIcsh\fR(1).
- Throughout this manual, features of
- \fItcsh\fR not found in most \fIcsh\fR(1) implementations
- (specifically, the 4.4BSD \fIcsh\fR)
- are labeled with `(+)', and features which are present in \fIcsh\fR(1)
- but not usually documented are labeled with `(u)'.
- .SS "Argument list processing"
- If the first argument (argument 0) to the shell is `\-' then it is a
- login shell. A login shell can be also specified by invoking the shell with
- the \fB\-l\fR flag as the only argument.
- .PP
- The rest of the flag arguments are interpreted as follows:
- .TP 4
- .B \-b
- Forces a ``break'' from option processing, causing any
- further shell arguments to be treated as non-option arguments. The remaining
- arguments will not be interpreted as shell options. This may be used to pass
- options to a shell script without confusion or possible subterfuge. The shell
- will not run a set-user ID script without this option.
- .TP 4
- .B \-c
- Commands are read from the following argument (which must be present, and
- must be a single argument),
- stored in the \fBcommand\fR shell variable for reference, and executed.
- Any remaining arguments are placed in the \fBargv\fR shell variable.
- .TP 4
- .B \-d
- The shell loads the directory stack from \fI~/.cshdirs\fR as described under
- \fBStartup and shutdown\fR, whether or not it is a login shell. (+)
- .TP 4
- .B \-D\fIname\fR[=\fIvalue\fR]
- Sets the environment variable \fIname\fR to \fIvalue\fR. (Domain/OS only) (+)
- .TP 4
- .B \-e
- The shell exits if any invoked command terminates abnormally or
- yields a non-zero exit status.
- .TP 4
- .B \-f
- The shell does not load any resource or startup files, or perform any
- command hashing, and thus starts faster.
- .TP 4
- .B \-F
- The shell uses \fIfork\fR(2) instead of \fIvfork\fR(2) to spawn processes. (+)
- .TP 4
- .B \-i
- The shell is interactive and prompts for its top-level input, even if
- it appears to not be a terminal. Shells are interactive without this option if
- their inputs and outputs are terminals.
- .TP 4
- .B \-l
- The shell is a login shell. Applicable only if \fB\-l\fR is the only
- flag specified.
- .TP 4
- .B \-m
- The shell loads \fI~/.tcshrc\fR even if it does not belong to the effective
- user. Newer versions of \fIsu\fR(1) can pass \fB\-m\fR to the shell. (+)
- .TP 4
- .B \-n
- The shell parses commands but does not execute them.
- This aids in debugging shell scripts.
- .TP 4
- .B \-q
- The shell accepts SIGQUIT (see \fBSignal handling\fR) and behaves when
- it is used under a debugger. Job control is disabled. (u)
- .TP 4
- .B \-s
- Command input is taken from the standard input.
- .TP 4
- .B \-t
- The shell reads and executes a single line of input. A `\\' may be used to
- escape the newline at the end of this line and continue onto another line.
- .TP 4
- .B \-v
- Sets the \fBverbose\fR shell variable, so that
- command input is echoed after history substitution.
- .TP 4
- .B \-x
- Sets the \fBecho\fR shell variable, so that commands are echoed
- immediately before execution.
- .TP 4
- .B \-V
- Sets the \fBverbose\fR shell variable even before executing \fI~/.tcshrc\fR.
- .TP 4
- .B \-X
- Is to \fB\-x\fR as \fB\-V\fR is to \fB\-v\fR.
- .TP 4
- .B \-\-help
- Print a help message on the standard output and exit. (+)
- .TP 4
- .B \-\-version
- Print the version/platform/compilation options on the standard output and exit.
- This information is also contained in the \fBversion\fR shell variable. (+)
- .PP
- After processing of flag arguments, if arguments remain but none of the
- \fB\-c\fR, \fB\-i\fR, \fB\-s\fR, or \fB\-t\fR options were given, the first
- argument is taken as the name of a file of commands, or ``script'', to
- be executed. The shell opens this file and saves its name for possible
- resubstitution by `$0'. Because many systems use either the standard
- version 6 or version 7 shells whose shell scripts are not compatible
- with this shell, the shell uses such a `standard' shell to execute a script
- whose first character is not a `#', i.e., that does not start with a
- comment.
- .PP
- Remaining arguments are placed in the \fBargv\fR shell variable.
- .SS "Startup and shutdown"
- A login shell begins by executing commands from the system files
- \fI/etc/csh.cshrc\fR and \fI/etc/csh.login\fR.
- It then executes commands from files in the user's \fBhome\fR directory:
- first \fI~/.tcshrc\fR (+)
- or, if \fI~/.tcshrc\fR is not found, \fI~/.cshrc\fR,
- then \fI~/.history\fR (or the value of the \fBhistfile\fR shell variable),
- then \fI~/.login\fR,
- and finally \fI~/.cshdirs\fR (or the value of the \fBdirsfile\fR shell variable) (+).
- The shell may read \fI/etc/csh.login\fR before instead of after
- \fI/etc/csh.cshrc\fR, and \fI~/.login\fR before instead of after
- \fI~/.tcshrc\fR or \fI~/.cshrc\fR and \fI~/.history\fR, if so compiled;
- see the \fBversion\fR shell variable. (+)
- .PP
- Non-login shells read only \fI/etc/csh.cshrc\fR and \fI~/.tcshrc\fR
- or \fI~/.cshrc\fR on startup.
- .PP
- For examples of startup files, please consult
- \fIhttp://tcshrc.sourceforge.net\fR.
- .PP
- Commands like \fIstty\fR(1) and \fItset\fR(1),
- which need be run only once per login, usually go in one's \fI~/.login\fR file.
- Users who need to use the same set of files with both \fIcsh\fR(1) and
- \fItcsh\fR can have only a \fI~/.cshrc\fR which checks for the existence of the
- \fBtcsh\fR shell variable (q.v.) before using \fItcsh\fR-specific commands,
- or can have both a \fI~/.cshrc\fR and a \fI~/.tcshrc\fR which \fIsource\fRs
- (see the builtin command) \fI~/.cshrc\fR.
- The rest of this manual uses `\fI~/.tcshrc\fR' to mean `\fI~/.tcshrc\fR or,
- if \fI~/.tcshrc\fR is not found, \fI~/.cshrc\fR'.
- .PP
- In the normal case, the shell begins reading commands from the terminal,
- prompting with `> '. (Processing of arguments and the use of the shell to
- process files containing command scripts are described later.)
- The shell repeatedly reads a line of command input, breaks it into words,
- places it on the command history list, parses it and executes each command
- in the line.
- .PP
- One can log out by typing `^D' on an empty line, `logout' or `login' or
- via the shell's autologout mechanism (see the \fBautologout\fR shell variable).
- When a login shell terminates it sets the \fBlogout\fR shell variable to
- `normal' or `automatic' as appropriate, then
- executes commands from the files
- \fI/etc/csh.logout\fR and \fI~/.logout\fR. The shell may drop DTR on logout
- if so compiled; see the \fBversion\fR shell variable.
- .PP
- The names of the system login and logout files vary from system to system for
- compatibility with different \fIcsh\fR(1) variants; see \fBFILES\fR.
- .SS Editing
- We first describe \fBThe command-line editor\fR.
- The \fBCompletion and listing\fR and \fBSpelling correction\fR sections
- describe two sets of functionality that are implemented as editor commands
- but which deserve their own treatment.
- Finally, \fBEditor commands\fR lists and describes
- the editor commands specific to the shell and their default bindings.
- .SS "The command-line editor (+)"
- Command-line input can be edited using key sequences much like those used in
- GNU Emacs or \fIvi\fR(1).
- The editor is active only when the \fBedit\fR shell variable is set, which
- it is by default in interactive shells.
- The \fIbindkey\fR builtin can display and change key bindings.
- Emacs-style key bindings are used by default
- (unless the shell was compiled otherwise; see the \fBversion\fR shell variable),
- but \fIbindkey\fR can change the key bindings to \fIvi\fR-style bindings en masse.
- .PP
- The shell always binds the arrow keys (as defined in the \fBTERMCAP\fR
- environment variable) to
- .PP
- .PD 0
- .RS +4
- .TP 8
- down
- \fIdown-history\fR
- .TP 8
- up
- \fIup-history\fR
- .TP 8
- left
- \fIbackward-char\fR
- .TP 8
- right
- \fIforward-char\fR
- .PD
- .RE
- .PP
- unless doing so would alter another single-character binding.
- One can set the arrow key escape sequences to the empty string with \fIsettc\fR
- to prevent these bindings.
- The ANSI/VT100 sequences for arrow keys are always bound.
- .PP
- Other key bindings are, for the most part, what Emacs and \fIvi\fR(1)
- users would expect and can easily be displayed by \fIbindkey\fR, so there
- is no need to list them here. Likewise, \fIbindkey\fR can list the editor
- commands with a short description of each.
- .PP
- Note that editor commands do not have the same notion of a ``word'' as does the
- shell. The editor delimits words with any non-alphanumeric characters not in
- the shell variable \fBwordchars\fR, while the shell recognizes only whitespace
- and some of the characters with special meanings to it, listed under
- \fBLexical structure\fR.
- .SS "Completion and listing (+)"
- The shell is often able to complete words when given a unique abbreviation.
- Type part of a word (for example `ls /usr/lost') and hit the tab key to
- run the \fIcomplete-word\fR editor command.
- The shell completes the filename `/usr/lost' to `/usr/lost+found/',
- replacing the incomplete word with the complete word in the input buffer.
- (Note the terminal `/'; completion adds a `/' to the
- end of completed directories and a space to the end of other completed words,
- to speed typing and provide a visual indicator of successful completion.
- The \fBaddsuffix\fR shell variable can be unset to prevent this.)
- If no match is found (perhaps `/usr/lost+found' doesn't exist),
- the terminal bell rings.
- If the word is already complete (perhaps there is a `/usr/lost' on your
- system, or perhaps you were thinking too far ahead and typed the whole thing)
- a `/' or space is added to the end if it isn't already there.
- .PP
- Completion works anywhere in the line, not at just the end; completed
- text pushes the rest of the line to the right. Completion in the middle of a word
- often results in leftover characters to the right of the cursor that need
- to be deleted.
- .PP
- Commands and variables can be completed in much the same way.
- For example, typing `em[tab]' would complete `em' to
- `emacs' if \fIemacs\fR were the only command on your system beginning with `em'.
- Completion can find a command in any directory in \fBpath\fR or if
- given a full pathname.
- Typing `echo $ar[tab]' would complete `$ar' to `$argv'
- if no other variable began with `ar'.
- .PP
- The shell parses the input buffer to determine whether the word you want to
- complete should be completed as a filename, command or variable.
- The first word in the buffer and the first word following
- `;', `|', `|&', `&&' or `||' is considered to be a command.
- A word beginning with `$' is considered to be a variable.
- Anything else is a filename. An empty line is `completed' as a filename.
- .PP
- You can list the possible completions of a word at any time by typing `^D'
- to run the \fIdelete-char-or-list-or-eof\fR editor command.
- The shell lists the possible completions using the \fIls\-F\fR builtin (q.v.)
- and reprints the prompt and unfinished command line, for example:
- .IP "" 4
- > ls /usr/l[^D]
- .br
- lbin/ lib/ local/ lost+found/
- .br
- > ls /usr/l
- .PP
- If the \fBautolist\fR shell variable is set, the shell lists the remaining
- choices (if any) whenever completion fails:
- .IP "" 4
- > set autolist
- .br
- > nm /usr/lib/libt[tab]
- .br
- libtermcap.a@ libtermlib.a@
- .br
- > nm /usr/lib/libterm
- .PP
- If \fBautolist\fR is set to `ambiguous', choices are listed only when
- completion fails and adds no new characters to the word being completed.
- .PP
- A filename to be completed can contain variables, your own or others' home
- directories abbreviated with `~' (see \fBFilename substitution\fR) and
- directory stack entries abbreviated with `='
- (see \fBDirectory stack substitution\fR). For example,
- .IP "" 4
- > ls ~k[^D]
- .br
- kahn kas kellogg
- .br
- > ls ~ke[tab]
- .br
- > ls ~kellogg/
- .PP
- or
- .IP "" 4
- > set local = /usr/local
- .br
- > ls $lo[tab]
- .br
- > ls $local/[^D]
- .br
- bin/ etc/ lib/ man/ src/
- .br
- > ls $local/
- .PP
- Note that variables can also be expanded explicitly with the
- \fIexpand-variables\fR editor command.
- .PP
- \fIdelete-char-or-list-or-eof\fR lists at only the end of the line;
- in the middle of a line it deletes the character under the cursor and
- on an empty line it logs one out or, if \fBignoreeof\fR is set, does nothing.
- `M-^D', bound to the editor command \fIlist-choices\fR, lists completion
- possibilities anywhere on a line, and \fIlist-choices\fR (or any one of the
- related editor commands that do or don't delete, list and/or log out,
- listed under \fIdelete-char-or-list-or-eof\fR) can be bound to `^D' with
- the \fIbindkey\fR builtin command if so desired.
- .PP
- The \fIcomplete-word-fwd\fR and \fIcomplete-word-back\fR editor commands
- (not bound to any keys by default) can be used to cycle up and down through
- the list of possible completions, replacing the current word with the next or
- previous word in the list.
- .PP
- The shell variable \fBfignore\fR can be set to a list of suffixes to be
- ignored by completion. Consider the following:
- .IP "" 4
- > ls
- .br
- Makefile condiments.h~ main.o side.c
- .br
- README main.c meal side.o
- .br
- condiments.h main.c~
- .br
- > set fignore = (.o \\~)
- .br
- > emacs ma[^D]
- .br
- main.c main.c~ main.o
- .br
- > emacs ma[tab]
- .br
- > emacs main.c
- .PP
- `main.c~' and `main.o' are ignored by completion (but not listing),
- because they end in suffixes in \fBfignore\fR.
- Note that a `\\' was needed in front of `~' to prevent it from being
- expanded to \fBhome\fR as described under \fBFilename substitution\fR.
- \fBfignore\fR is ignored if only one completion is possible.
- .PP
- If the \fBcomplete\fR shell variable is 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. If you had the following files
- .IP "" 4
- comp.lang.c comp.lang.perl comp.std.c++
- .br
- comp.lang.c++ comp.std.c
- .PP
- and typed `mail \-f c.l.c[tab]', it would be completed to
- `mail \-f comp.lang.c', and ^D would list `comp.lang.c' and `comp.lang.c++'.
- `mail \-f c..c++[^D]' would list `comp.lang.c++' and `comp.std.c++'. Typing
- `rm a\-\-file[^D]' in the following directory
- .IP "" 4
- A_silly_file a-hyphenated-file another_silly_file
- .PP
- would list all three files, because case is ignored and hyphens and
- underscores are equivalent. Periods, however, are not equivalent to
- hyphens or underscores.
- .PP
- If the \fBcomplete\fR shell variable is set to `Enhance', completion
- ignores case and differences between a hyphen and an underscore word
- separator only when the user types a lowercase character or a hyphen.
- Entering an uppercase character or an underscore will not match the
- corresponding lowercase character or hyphen word separator.
- Typing `rm a\-\-file[^D]' in the directory of the previous example would
- still list all three files, but typing `rm A\-\-file' would match only
- `A_silly_file' and typing `rm a__file[^D]' would match just `A_silly_file'
- and `another_silly_file' because the user explicitly used an uppercase
- or an underscore character.
- .PP
- Completion and listing are affected by several other shell variables:
- \fBrecexact\fR can be set to complete on the shortest possible unique
- match, even if more typing might result in a longer match:
- .IP "" 4
- > ls
- .br
- fodder foo food foonly
- .br
- > set recexact
- .br
- > rm fo[tab]
- .PP
- just beeps, because `fo' could expand to `fod' or `foo', but if we type
- another `o',
- .IP "" 4
- > rm foo[tab]
- .br
- > rm foo
- .PP
- the completion completes on `foo', even though `food' and `foonly'
- also match.
- \fBautoexpand\fR can be set to run the \fIexpand-history\fR editor command
- before each completion attempt, \fBautocorrect\fR can be set to
- spelling-correct the word to be completed (see \fBSpelling correction\fR)
- before each completion attempt and \fBcorrect\fR can be set to complete
- commands automatically after one hits `return'.
- \fBmatchbeep\fR can be set to make completion beep or not beep in a variety
- of situations, and \fBnobeep\fR can be set to never beep at all.
- \fBnostat\fR can be set to a list of directories and/or patterns that
- match directories to prevent the completion mechanism from \fIstat\fR(2)ing
- those directories.
- \fBlistmax\fR and \fBlistmaxrows\fR can be set to limit the number of items
- and rows (respectively) that are listed without asking first.
- \fBrecognize_only_executables\fR can be set to make the shell list only
- executables when listing commands, but it is quite slow.
- .PP
- Finally, the \fIcomplete\fR builtin command can be used to tell the shell how
- to complete words other than filenames, commands and variables.
- Completion and listing do not work on glob-patterns (see \fBFilename substitution\fR),
- but the \fIlist-glob\fR and \fIexpand-glob\fR editor commands perform
- equivalent functions for glob-patterns.
- .SS "Spelling correction (+)"
- The shell can sometimes correct the spelling of filenames, commands and variable names
- as well as completing and listing them.
- .PP
- Individual words can be spelling-corrected with the \fIspell-word\fR
- editor command (usually bound to M-s and M-S)
- and the entire input buffer with \fIspell-line\fR (usually bound to M-$).
- The \fBcorrect\fR shell variable can be set to `cmd' to correct the
- command name or `all' to correct the entire line each time return is typed,
- and \fBautocorrect\fR can be set to correct the word to be completed
- before each completion attempt.
- .PP
- When spelling correction is invoked in any of these ways and
- the shell thinks that any part of the command line is misspelled,
- it prompts with the corrected line:
- .IP "" 4
- > set correct = cmd
- .br
- > lz /usr/bin
- .br
- CORRECT>ls /usr/bin (y|n|e|a)?
- .PP
- One can answer `y' or space to execute the corrected line,
- `e' to leave the uncorrected command in the input buffer,
- `a' to abort the command as if `^C' had been hit, and
- anything else to execute the original line unchanged.
- .PP
- Spelling correction recognizes user-defined completions (see the
- \fIcomplete\fR builtin command). If an input word in a position for
- which a completion is defined resembles a word in the completion list,
- spelling correction registers a misspelling and suggests the latter
- word as a correction. However, if the input word does not match any of
- the possible completions for that position, spelling correction does
- not register a misspelling.
- .PP
- Like completion, spelling correction works anywhere in the line,
- pushing the rest of the line to the right and possibly leaving
- extra characters to the right of the cursor.
- .PP
- Beware: spelling correction is not guaranteed to work the way one intends,
- and is provided mostly as an experimental feature.
- Suggestions and improvements are welcome.
- .SS "Editor commands (+)"
- `bindkey' lists key bindings and `bindkey \-l' lists and briefly describes
- editor commands.
- Only new or especially interesting editor commands are described here.
- See \fIemacs\fR(1) and \fIvi\fR(1) for descriptions of each editor's
- key bindings.
- .PP
- The character or characters to which each command is bound by default is
- given in parentheses. `^\fIcharacter\fR' means a control character and
- `M-\fIcharacter\fR' a meta character, typed as escape-\fIcharacter\fR
- on terminals without a meta key. Case counts, but commands that are bound
- to letters by default are bound to both lower- and uppercase letters for
- convenience.
- .TP 8
- .B complete-word \fR(tab)
- Completes a word as described under \fBCompletion and listing\fR.
- .TP 8
- .B complete-word-back \fR(not bound)
- Like \fIcomplete-word-fwd\fR, but steps up from the end of the list.
- .TP 8
- .B complete-word-fwd \fR(not bound)
- Replaces the current word with the first word in the list of possible
- completions. May be repeated to step down through the list.
- At the end of the list, beeps and reverts to the incomplete word.
- .TP 8
- .B complete-word-raw \fR(^X-tab)
- Like \fIcomplete-word\fR, but ignores user-defined completions.
- .TP 8
- .B copy-prev-word \fR(M-^_)
- Copies the previous word in the current line into the input buffer.
- See also \fIinsert-last-word\fR.
- .TP 8
- .B dabbrev-expand \fR(M-/)
- Expands the current word to the most recent preceding one for which
- the current is a leading substring, wrapping around the history list
- (once) if necessary.
- Repeating \fIdabbrev-expand\fR without any intervening typing
- changes to the next previous word etc., skipping identical matches
- much like \fIhistory-search-backward\fR does.
- .TP 8
- .B delete-char \fR(not bound)
- Deletes the character under the cursor.
- See also \fIdelete-char-or-list-or-eof\fR.
- .TP 8
- .B delete-char-or-eof \fR(not bound)
- Does \fIdelete-char\fR if there is a character under the cursor
- or \fIend-of-file\fR on an empty line.
- See also \fIdelete-char-or-list-or-eof\fR.
- .TP 8
- .B delete-char-or-list \fR(not bound)
- Does \fIdelete-char\fR if there is a character under the cursor
- or \fIlist-choices\fR at the end of the line.
- See also \fIdelete-char-or-list-or-eof\fR.
- .TP 8
- .B delete-char-or-list-or-eof \fR(^D)
- Does \fIdelete-char\fR if there is a character under the cursor,
- \fIlist-choices\fR at the end of the line
- or \fIend-of-file\fR on an empty line.
- See also those three commands, each of which does only a single action, and
- \fIdelete-char-or-eof\fR, \fIdelete-char-or-list\fR and \fIlist-or-eof\fR,
- each of which does a different two out of the three.
- .TP 8
- .B down-history \fR(down-arrow, ^N)
- Like \fIup-history\fR, but steps down, stopping at the original input line.
- .TP 8
- .B end-of-file \fR(not bound)
- Signals an end of file, causing the shell to exit unless the \fBignoreeof\fR
- shell variable (q.v.) is set to prevent this.
- See also \fIdelete-char-or-list-or-eof\fR.
- .TP 8
- .B expand-history \fR(M-space)
- Expands history substitutions in the current word.
- See \fBHistory substitution\fR.
- See also \fImagic-space\fR, \fItoggle-literal-history\fR and
- the \fBautoexpand\fR shell variable.
- .TP 8
- .B expand-glob \fR(^X-*)
- Expands the glob-pattern to the left of the cursor.
- See \fBFilename substitution\fR.
- .TP 8
- .B expand-line \fR(not bound)
- Like \fIexpand-history\fR, but
- expands history substitutions in each word in the input buffer.
- .TP 8
- .B expand-variables \fR(^X-$)
- Expands the variable to the left of the cursor.
- See \fBVariable substitution\fR.
- .TP 8
- .B history-search-backward \fR(M-p, M-P)
- Searches backwards through the history list for a command beginning with
- the current contents of the input buffer up to the cursor and copies it
- into the input buffer.
- The search string may be a glob-pattern (see \fBFilename substitution\fR)
- containing `*', `?', `[]' or `{}'.
- \fIup-history\fR and \fIdown-history\fR will proceed from the
- appropriate point in the history list.
- Emacs mode only.
- See also \fIhistory-search-forward\fR and \fIi-search-back\fR.
- .TP 8
- .B history-search-forward \fR(M-n, M-N)
- Like \fIhistory-search-backward\fR, but searches forward.
- .TP 8
- .B i-search-back \fR(not bound)
- Searches backward like \fIhistory-search-backward\fR, copies the first match
- into the input buffer with the cursor positioned at the end of the pattern,
- and prompts with `bck: ' and the first match. Additional characters may be
- typed to extend the search, \fIi-search-back\fR may be typed to continue
- searching with the same pattern, wrapping around the history list if
- necessary, (\fIi-search-back\fR must be bound to a
- single character for this to work) or one of the following special characters
- may be typed:
- .PP
- .RS +8
- .RS +4
- .PD 0
- .TP 8
- ^W
- Appends the rest of the word under the cursor to the search pattern.
- .TP 8
- delete (or any character bound to \fIbackward-delete-char\fR)
- Undoes the effect of the last character typed and deletes a character
- from the search pattern if appropriate.
- .TP 8
- ^G
- If the previous search was successful, aborts the entire search.
- If not, goes back to the last successful search.
- .TP 8
- escape
- Ends the search, leaving the current line in the input buffer.
- .RE
- .PD
- .PP
- Any other character not bound to \fIself-insert-command\fR terminates the
- search, leaving the current line in the input buffer, and
- is then interpreted as normal input. In particular, a carriage return
- causes the current line to be executed.
- Emacs mode only.
- See also \fIi-search-fwd\fR and \fIhistory-search-backward\fR.
- .RE
- .TP 8
- .B i-search-fwd \fR(not bound)
- Like \fIi-search-back\fR, but searches forward.
- .TP 8
- .B insert-last-word \fR(M-_)
- Inserts the last word of the previous input line (`!$') into the input buffer.
- See also \fIcopy-prev-word\fR.
- .TP 8
- .B list-choices \fR(M-^D)
- Lists completion possibilities as described under \fBCompletion and listing\fR.
- See also \fIdelete-char-or-list-or-eof\fR and \fIlist-choices-raw\fR.
- .TP 8
- .B list-choices-raw \fR(^X-^D)
- Like \fIlist-choices\fR, but ignores user-defined completions.
- .TP 8
- .B list-glob \fR(^X-g, ^X-G)
- Lists (via the \fIls\-F\fR builtin) matches to the glob-pattern
- (see \fBFilename substitution\fR) to the left of the cursor.
- .TP 8
- .B list-or-eof \fR(not bound)
- Does \fIlist-choices\fR
- or \fIend-of-file\fR on an empty line.
- See also \fIdelete-char-or-list-or-eof\fR.
- .TP 8
- .B magic-space \fR(not bound)
- Expands history substitutions in the current line,
- like \fIexpand-history\fR, and inserts a space.
- \fImagic-space\fR is designed to be bound to the space bar,
- but is not bound by default.
- .TP 8
- .B normalize-command \fR(^X-?)
- Searches for the current word in PATH and, if it is found, replaces it with
- the full path to the executable. Special characters are quoted. Aliases are
- expanded and quoted but commands within aliases are not. This command is
- useful with commands that take commands as arguments, e.g., `dbx' and `sh \-x'.
- .TP 8
- .B normalize-path \fR(^X-n, ^X-N)
- Expands the current word as described under the `expand' setting
- of the \fBsymlinks\fR shell variable.
- .TP 8
- .B overwrite-mode \fR(unbound)
- Toggles between input and overwrite modes.
- .TP 8
- .B run-fg-editor \fR(M-^Z)
- Saves the current input line and
- looks for a stopped job with a name equal to the last component of the
- file name part of the \fBEDITOR\fR or \fBVISUAL\fR environment variables,
- or, if neither is set, `ed' or `vi'.
- If such a job is found, it is restarted as if `fg %\fIjob\fR' had been
- typed. This is used to toggle back and forth between an editor and
- the shell easily. Some people bind this command to `^Z' so they
- can do this even more easily.
- .TP
- .B run-help \fR(M-h, M-H)
- Searches for documentation on the current command, using the same notion of
- `current command' as the completion routines, and prints it. There is no way
- to use a pager; \fIrun-help\fR is designed for short help files.
- If the special alias \fBhelpcommand\fR is defined, it is run with the
- command name as a sole argument. Else,
- documentation should be in a file named \fIcommand\fR.help, \fIcommand\fR.1,
- \fIcommand\fR.6, \fIcommand\fR.8 or \fIcommand\fR, which should be in one
- of the directories listed in the \fBHPATH\fR environment variable.
- If there is more than one help file only the first is printed.
- .TP 8
- .B self-insert-command \fR(text characters)
- In insert mode (the default), inserts the typed character into the input line after the character under the cursor.
- In overwrite mode, replaces the character under the cursor with the typed character.
- The input mode is normally preserved between lines, but the
- \fBinputmode\fR shell variable can be set to `insert' or `overwrite' to put the
- editor in that mode at the beginning of each line.
- See also \fIoverwrite-mode\fR.
- .TP 8
- .B sequence-lead-in \fR(arrow prefix, meta prefix, ^X)
- Indicates that the following characters are part of a
- multi-key sequence. Binding a command to a multi-key sequence really creates
- two bindings: the first character to \fIsequence-lead-in\fR and the
- whole sequence to the command. All sequences beginning with a character
- bound to \fIsequence-lead-in\fR are effectively bound to \fIundefined-key\fR
- unless bound to another command.
- .TP 8
- .B spell-line \fR(M-$)
- Attempts to correct the spelling of each word in the input buffer, like
- \fIspell-word\fR, but ignores words whose first character is one of
- `\-', `!', `^' or `%', or which contain `\\', `*' or `?', to avoid problems
- with switches, substitutions and the like.
- See \fBSpelling correction\fR.
- .TP 8
- .B spell-word \fR(M-s, M-S)
- Attempts to correct the spelling of the current word as described
- under \fBSpelling correction\fR.
- Checks each component of a word which appears to be a pathname.
- .TP 8
- .B toggle-literal-history \fR(M-r, M-R)
- Expands or `unexpands' history substitutions in the input buffer.
- See also \fIexpand-history\fR and the \fBautoexpand\fR shell variable.
- .TP 8
- .B undefined-key \fR(any unbound key)
- Beeps.
- .TP 8
- .B up-history \fR(up-arrow, ^P)
- Copies the previous entry in the history list into the input buffer.
- If \fBhistlit\fR is set, uses the literal form of the entry.
- May be repeated to step up through the history list, stopping at the top.
- .TP 8
- .B vi-search-back \fR(?)
- Prompts with `?' for a search string (which may be a glob-pattern, as with
- \fIhistory-search-backward\fR), searches for it and copies it into the
- input buffer. The bell rings if no match is found.
- Hitting return ends the search and leaves the last match in the input
- buffer.
- Hitting escape ends the search and executes the match.
- \fIvi\fR mode only.
- .TP 8
- .B vi-search-fwd \fR(/)
- Like \fIvi-search-back\fR, but searches forward.
- .TP 8
- .B which-command \fR(M-?)
- Does a \fIwhich\fR (see the description of the builtin command) on the
- first word of the input buffer.
- .TP 8
- .B yank-pop \fR(M-y)
- When executed immediately after a \fIyank\fR or another \fIyank-pop\fR,
- replaces the yanked string with the next previous string from the
- killring. This also has the effect of rotating the killring, such that
- this string will be considered the most recently killed by a later
- \fIyank\fR command. Repeating \fIyank-pop\fR will cycle through the
- killring any number of times.
- .SS "Lexical structure"
- The shell splits input lines into words at blanks and tabs. The special
- characters `&', `|', `;', `<', `>', `(', and `)' and the doubled characters
- `&&', `||', `<<' and `>>' are always separate words, whether or not they are
- surrounded by whitespace.
- .PP
- When the shell's input is not a terminal, the character `#' is taken to begin a
- comment. Each `#' and the rest of the input line on which it appears is
- discarded before further parsing.
- .PP
- A special character (including a blank or tab) may be prevented from having
- its special meaning, and possibly made part of another word, by preceding it
- with a backslash (`\\') or enclosing it in single (`''), double (`"') or
- backward (``') quotes. When not otherwise quoted a newline preceded by a `\\'
- is equivalent to a blank, but inside quotes this sequence results in a
- newline.
- .PP
- Furthermore, all \fBSubstitutions\fR (see below) except \fBHistory substitution\fR
- can be prevented by enclosing the strings (or parts of strings)
- in which they appear with single quotes or by quoting the crucial character(s)
- (e.g., `$' or ``' for \fBVariable substitution\fR or \fBCommand substitution\fR respectively)
- with `\\'. (\fBAlias substitution\fR is no exception: quoting in any way any
- character of a word for which an \fIalias\fR has been defined prevents
- substitution of the alias. The usual way of quoting an alias is to precede it
- with a backslash.) \fBHistory substitution\fR is prevented by
- backslashes but not by single quotes. Strings quoted with double or backward
- quotes undergo \fBVariable substitution\fR and \fBCommand substitution\fR, but other
- substitutions are prevented.
- .PP
- Text inside single or double quotes becomes a single word (or part of one).
- Metacharacters in these strings, including blanks and tabs, do not form
- separate words. Only in one special case (see \fBCommand substitution\fR
- below) can a double-quoted string yield parts of more than one word;
- single-quoted strings never do. Backward quotes are special: they signal
- \fBCommand substitution\fR (q.v.), which may result in more than one word.
- .PP
- Quoting complex strings, particularly strings which themselves contain quoting
- characters, can be confusing. Remember that quotes need not be used as they are
- in human writing! It may be easier to quote not an entire string, but only
- those parts of the string which need quoting, using different types of quoting
- to do so if appropriate.
- .PP
- The \fBbackslash_quote\fR shell variable (q.v.) can be set to make backslashes
- always quote `\\', `'', and `"'. (+) This may make complex quoting tasks
- easier, but it can cause syntax errors in \fIcsh\fR(1) scripts.
- .SS Substitutions
- We now describe the various transformations the shell performs on the input in
- the order in which they occur. We note in passing the data structures involved
- and the commands and variables which affect them. Remember that substitutions
- can be prevented by quoting as described under \fBLexical structure\fR.
- .SS "History substitution"
- Each command, or ``event'', input from the terminal is saved in the history
- list. The previous command is always saved, and the \fBhistory\fR shell
- variable can be set to a number to save that many commands. The \fBhistdup\fR
- shell variable can be set to not save duplicate events or consecutive duplicate
- events.
- .PP
- Saved commands are numbered sequentially from 1 and stamped with the time.
- It is not usually necessary to use event numbers, but the current event number
- can be made part of the prompt by placing an `!' in the \fBprompt\fR shell variable.
- .PP
- The shell actually saves history in expanded and literal (unexpanded) forms.
- If the \fBhistlit\fR shell variable is set, commands that display and store
- history use the literal form.
- .PP
- The \fIhistory\fR builtin command can print, store in a file, restore
- and clear the history list at any time,
- and the \fBsavehist\fR and \fBhistfile\fR shell variables can be set to
- store the history list automatically on logout and restore it on login.
- .PP
- History substitutions introduce words from the history list into the input
- stream, making it easy to repeat commands, repeat arguments of a previous
- command in the current command, or fix spelling mistakes in the previous
- command with little typing and a high degree of confidence.
- .PP
- History substitutions begin with the character `!'. They may begin anywhere in
- the input stream, but they do not nest. The `!' may be preceded by a `\\' to
- prevent its special meaning; for convenience, a `!' is passed unchanged when it
- is followed by a blank, tab, newline, `=' or `('. History substitutions also
- occur when an input line begins with `^'. This special abbreviation will be
- described later. The characters used to signal history substitution (`!' and
- `^') can be changed by setting the \fBhistchars\fR shell variable. Any input
- line which contains a history substitution is printed before it is executed.
- .PP
- A history substitution may have an ``event specification'', which indicates
- the event from which words are to be taken, a ``word designator'',
- which selects particular words from the chosen event, and/or a ``modifier'',
- which manipulates the selected words.
- .PP
- An event specification can be
- .PP
- .PD 0
- .RS +4
- .TP 8
- .I n
- A number, referring to a particular event
- .TP 8
- \-\fIn\fR
- An offset, referring to the event \fIn\fR before the current event
- .TP 8
- #
- The current event.
- This should be used carefully in \fIcsh\fR(1), where there is no check for
- recursion. \fItcsh\fR allows 10 levels of recursion. (+)
- .TP 8
- !
- The previous event (equivalent to `\-1')
- .TP 8
- .I s
- The most recent event whose first word begins with the string \fIs\fR
- .TP 8
- ?\fIs\fR?
- The most recent event which contains the string \fIs\fR.
- The second `?' can be omitted if it is immediately followed by a newline.
- .RE
- .PD
- .PP
- For example, consider this bit of someone's history list:
- .IP "" 4
- \ 9 8:30 nroff \-man wumpus.man
- .br
- 10 8:31 cp wumpus.man wumpus.man.old
- .br
- 11 8:36 vi wumpus.man
- .br
- 12 8:37 diff wumpus.man.old wumpus.man
- .PP
- The commands are shown with their event numbers and time stamps.
- The current event, which we haven't typed in yet, is event 13.
- `!11' and `!\-2' refer to event 11.
- `!!' refers to the previous event, 12. `!!' can be abbreviated `!' if it is
- followed by `:' (`:' is described below).
- `!n' refers to event 9, which begins with `n'.
- `!?old?' also refers to event 12, which contains `old'.
- Without word designators or modifiers history references simply expand to the
- entire event, so we might type `!cp' to redo the copy command or `!!|more'
- if the `diff' output scrolled off the top of the screen.
- .PP
- History references may be insulated from the surrounding text with braces if
- necessary. For example, `!vdoc' would look for a command beginning with
- `vdoc', and, in this example, not find one, but `!{v}doc' would expand
- unambiguously to `vi wumpus.mandoc'.
- Even in braces, history substitutions do not nest.
- .PP
- (+) While \fIcsh\fR(1) expands, for example, `!3d' to event 3 with the
- letter `d' appended to it, \fItcsh\fR expands it to the last event beginning
- with `3d'; only completely numeric arguments are treated as event numbers.
- This makes it possible to recall events beginning with numbers.
- To expand `!3d' as in \fIcsh\fR(1) say `!{3}d'.
- .PP
- To select words from an event we can follow the event specification by a `:'
- and a designator for the desired words. The words of an input line are
- numbered from 0, the first (usually command) word being 0, the second word
- (first argument) being 1, etc. The basic word designators are:
- .PP
- .PD 0
- .RS +4
- .TP 8
- 0
- The first (command) word
- .TP 8
- .I n
- The \fIn\fRth argument
- .TP 8
- ^
- The first argument, equivalent to `1'
- .TP 8
- $
- The last argument
- .TP 8
- %
- The word matched by an ?\fIs\fR? search
- .TP 8
- .I x\-y
- A range of words
- .TP 8
- .I \-y
- Equivalent to \fI`0\-y'\fR
- .TP 8
- *
- Equivalent to `^\-$', but returns nothing if the event contains only 1 word
- .TP 8
- .I x*
- Equivalent to \fI`x\-$'\fR
- .TP 8
- .I x\-
- Equivalent to \fI`x*'\fR, but omitting the last word (`$')
- .PD
- .RE
- .PP
- Selected words are inserted into the command line separated by single blanks.
- For example, the `diff' command in the previous example might have been
- typed as `diff !!:1.old !!:1' (using `:1' to select the first argument
- from the previous event) or `diff !\-2:2 !\-2:1' to select and swap the
- arguments from the `cp' command. If we didn't care about the order of the
- `diff' we might have said `diff !\-2:1\-2' or simply `diff !\-2:*'.
- The `cp' command might have been written `cp wumpus.man !#:1.old', using `#'
- to refer to the current event.
- `!n:\- hurkle.man' would reuse the first two words from the `nroff' command
- to say `nroff \-man hurkle.man'.
- .PP
- The `:' separating the event specification from the word designator can be
- omitted if the argument selector begins with a `^', `$', `*', `%' or `\-'.
- For example, our `diff' command might have been `diff !!^.old !!^' or,
- equivalently, `diff !!$.old !!$'. However, if `!!' is abbreviated `!',
- an argument selector beginning with `\-' will be interpreted as an event
- specification.
- .PP
- A history reference may have a word designator but no event specification.
- It then references the previous command.
- Continuing our `diff' example, we could have said simply `diff
- !^.old !^' or, to get the arguments in the opposite order, just `diff !*'.
- .PP
- The word or words in a history reference can be edited, or ``modified'',
- by following it with one or more modifiers, each preceded by a `:':
- .PP
- .PD 0
- .RS +4
- .TP 8
- h
- Remove a trailing pathname component, leaving the head.
- .TP 8
- t
- Remove all leading pathname components, leaving the tail.
- .TP 8
- r
- Remove a filename extension `.xxx', leaving the root name.
- .TP 8
- e
- Remove all but the extension.
- .TP 8
- u
- Uppercase the first lowercase letter.
- .TP 8
- l
- Lowercase the first uppercase letter.
- .TP 8
- s\fI/l/r/\fR
- Substitute \fIl\fR for \fIr\fR.
- \fIl\fR is simply a string like \fIr\fR, not a regular expression as in
- the eponymous \fIed\fR(1) command.
- Any character may be used as the delimiter in place of `/';
- a `\\' can be used to quote the delimiter inside \fIl\fR and \fIr\fR.
- The character `&' in the \fIr\fR is replaced by \fIl\fR; `\\' also quotes `&'.
- If \fIl\fR is empty (``''), the \fIl\fR from a previous substitution or the
- \fIs\fR from a previous search or event number in event specification is used.
- The trailing delimiter may be omitted if it is immediately followed by a newline.
- .TP 8
- &
- Repeat the previous substitution.
- .TP 8
- g
- Apply the following modifier once to each word.
- .TP 8
- a (+)
- Apply the following modifier as many times as possible to a single word.
- `a' and `g' can be used together to apply a modifier globally.
- With the `s' modifier, only the patterns contained in the original word are
- substituted, not patterns that contain any substitution result.
- .TP 8
- p
- Print the new command line but do not execute it.
- .TP 8
- q
- Quote the substituted words, preventing further substitutions.
- .TP 8
- x
- Like q, but break into words at blanks, tabs and newlines.
- .PD
- .RE
- .PP
- Modifiers are applied to only the first modifiable word (unless `g' is used).
- It is an error for no word to be modifiable.
- .PP
- For example, the `diff' command might have been written as `diff wumpus.man.old
- !#^:r', using `:r' to remove `.old' from the first argument on the same line
- (`!#^'). We could say `echo hello out there', then `echo !*:u' to capitalize
- `hello', `echo !*:au' to say it out loud, or `echo !*:agu' to really shout.
- We might follow `mail \-s "I forgot my password" rot' with `!:s/rot/root' to
- correct the spelling of `root' (but see \fBSpelling correction\fR for a
- different approach).
- .PP
- There is a special abbreviation for substitutions.
- `^', when it is the first character on an input line, is equivalent to `!:s^'.
- Thus we might have said `^rot^root' to make the spelling correction in the
- previous example.
- This is the only history substitution which does not explicitly begin with `!'.
- .PP
- (+) In \fIcsh\fR as such, only one modifier may be applied to each history
- or variable expansion. In \fItcsh\fR, more than one may be used, for example
- .IP "" 4
- % mv wumpus.man /usr/man/man1/wumpus.1
- .br
- % man !$:t:r
- .br
- man wumpus
- .PP
- In \fIcsh\fR, the result would be `wumpus.1:r'. A substitution followed by a
- colon may need to be insulated from it with braces:
- .IP "" 4
- > mv a.out /usr/games/wumpus
- .br
- > setenv PATH !$:h:$PATH
- .br
- Bad ! modifier: $.
- .br
- > setenv PATH !{\-2$:h}:$PATH
- .br
- setenv PATH /usr/games:/bin:/usr/bin:.
- .PP
- The first attempt would succeed in \fIcsh\fR but fails in \fItcsh\fR,
- because \fItcsh\fR expects another modifier after the second colon
- rather than `$'.
- .PP
- Finally, history can be accessed through the editor as well as through
- the substitutions just described.
- The \fIup-\fR and \fIdown-history\fR, \fIhistory-search-backward\fR and
- \fI-forward\fR, \fIi-search-back\fR and \fI-fwd\fR,
- \fIvi-search-back\fR and \fI-fwd\fR, \fIcopy-prev-word\fR
- and \fIinsert-last-word\fR editor commands search for
- events in the history list and copy them into the input buffer.
- The \fItoggle-literal-history\fR editor command switches between the
- expanded and literal forms of history lines in the input buffer.
- \fIexpand-history\fR and \fIexpand-line\fR expand history substitutions
- in the current word and in the entire input buffer respectively.
- .SS "Alias substitution"
- The shell maintains a list of aliases which can be set, unset and printed by
- the \fIalias\fR and \fIunalias\fR commands. After a command line is parsed
- into simple commands (see \fBCommands\fR) the first word of each command,
- left-to-right, is checked to see if it has an alias. If so, the first word is
- replaced by the alias. If the alias contains a history reference, it undergoes
- \fBHistory substitution\fR (q.v.) as though the original command were the
- previous input line. If the alias does not contain a history reference, the
- argument list is left untouched.
- .PP
- Thus if the alias for `ls' were `ls \-l' the command `ls /usr' would become `ls
- \-l /usr', the argument list here being undisturbed. If the alias for `lookup'
- were `grep !^ /etc/passwd' then `lookup bill' would become `grep bill
- /etc/passwd'. Aliases can be used to introduce parser metasyntax. For
- example, `alias print 'pr \e!* | lpr'' defines a ``command'' (`print') which
- \fIpr\fR(1)s its arguments to the line printer.
- .PP
- Alias substitution is repeated until the first word of the command has no
- alias. If an alias substitution does not change the first word (as in the
- previous example) it is flagged to prevent a loop. Other loops are detected and
- cause an error.
- .PP
- Some aliases are referred to by the shell; see \fBSpecial aliases\fR.
- .SS "Variable substitution"
- The shell maintains a list of variables, each of which has as value a list of
- zero or more words.
- The values of shell variables can be displayed and changed with the
- \fIset\fR and \fIunset\fR commands.
- The system maintains its own list of ``environment'' variables.
- These can be displayed and changed with \fIprintenv\fR, \fIsetenv\fR and
- \fIunsetenv\fR.
- .PP
- (+) Variables may be made read-only with `set \-r' (q.v.).
- Read-only variables may not be modified or unset;
- attempting to do so will cause an error.
- Once made read-only, a variable cannot be made writable,
- so `set \-r' should be used with caution.
- Environment variables cannot be made read-only.
- .PP
- Some variables are set by the shell or referred to by it.
- For instance, the \fBargv\fR variable is an image of the shell's argument
- list, and words of this variable's value are referred to in special ways.
- Some of the variables referred to by the shell are toggles;
- the shell does not care what their value is, only whether they are set or not.
- For instance, the \fBverbose\fR variable is a toggle which causes command
- input to be echoed. The \fB\-v\fR command line option sets this variable.
- \fBSpecial shell variables\fR lists all variables which are referred to by the shell.
- .PP
- Other operations treat variables numerically. The `@' command permits numeric
- calculations to be performed and the result assigned to a variable. Variable
- values are, however, always represented as (zero or more) strings. For the
- purposes of numeric operations, the null string is considered to be zero, and
- the second and subsequent words of multi-word values are ignored.
- .PP
- After the input line is aliased and parsed, and before each command is
- executed, variable substitution is performed keyed by `$' characters. This
- expansion can be prevented by preceding the `$' with a `\e' except within `"'s
- where it \fIalways\fR occurs, and within `''s where it \fInever\fR occurs.
- Strings quoted by ``' are interpreted later (see \fBCommand substitution\fR
- below) so `$' substitution does not occur there until later,
- if at all. A `$' is passed unchanged if followed by a blank, tab, or
- end-of-line.
- .PP
- Input/output redirections are recognized before variable expansion, and are
- variable expanded separately. Otherwise, the command name and entire argument
- list are expanded together. It is thus possible for the first (command) word
- (to this point) to generate more than one word, the first of which becomes the
- command name, and the rest of which become arguments.
- .PP
- Unless enclosed in `"' or given the `:q' modifier the results of variable
- substitution may eventually be command and filename substituted. Within `"', a
- variable whose value consists of multiple words expands to a (portion of a)
- single word, with the words of the variable's value separated by blanks. When
- the `:q' modifier is applied to a substitution the variable will expand to
- multiple words with each word separated by a blank and quoted to prevent later
- command or filename substitution.
- .PP
- The following metasequences are provided for introducing variable values into
- the shell input. Except as noted, it is an error to reference a variable which
- is not set.
- .PP
- .PD 0
- $\fIname\fR
- .TP 8
- ${\fIname\fR}
- Substitutes the words of the value of variable \fIname\fR, each separated
- by a blank. Braces insulate \fIname\fR from following characters which would
- otherwise be part of it. Shell variables have names consisting of
- letters and digits starting with a letter. The underscore character is
- considered a letter. If \fIname\fR is not a shell variable, but is set in the
- environment, then that value is returned (but some of the other forms
- given below are not available in this case).
- .PP
- $\fIname\fR[\fIselector\fR]
- .TP 8
- ${\fIname\fR[\fIselector\fR]}
- Substitutes only the selected words from the value of \fIname\fR.
- The \fIselector\fR is subjected to `$' substitution and may consist of
- a single number or two numbers separated by a `\-'.
- The first word of a variable's value is numbered `1'.
- If the first number of a range is omitted it defaults to `1'.
- If the last member of a range is omitted it defaults to `$#\fIname\fR'.
- The \fIselector\fR `*' selects all words.
- It is not an error for a range to be empty if the
- second argument is omitted or in range.
- .TP 8
- $0
- Substitutes the name of the file from which command input
- is being read. An error occurs if the name is not known.
- .PP
- $\fInumber\fR
- .TP 8
- ${\fInumber\fR}
- Equivalent to `$argv[\fInumber\fR]'.
- .TP 8
- $*
- Equivalent to `$argv', which is equivalent to `$argv[*]'.
- .PD
- .PP
- The `:' modifiers described under \fBHistory substitution\fR, except for `:p',
- can be applied to the substitutions above. More than one may be used. (+)
- Braces may be needed to insulate a variable substitution from a literal colon
- just as with \fBHistory substitution\fR (q.v.); any modifiers must appear
- within the braces.
- .PP
- The following substitutions can not be modified with `:' modifiers.
- .PP
- .PD 0
- $?\fIname\fR
- .TP 8
- ${?\fIname\fR}
- Substitutes the string `1' if \fIname\fR is set, `0' if it is not.
- .TP 8
- $?0
- Substitutes `1' if the current input filename is known, `0' if it is not.
- Always `0' in interactive shells.
- .PP
- $#\fIname\fR
- .TP 8
- ${#\fIname\fR}
- Substitutes the number of words in \fIname\fR.
- .TP 8
- $#
- Equivalent to `$#argv'. (+)
- .PP
- $%\fIname\fR
- .TP 8
- ${%\fIname\fR}
- Substitutes the number of characters in \fIname\fR. (+)
- .PP
- $%\fInumber\fR
- .TP 8
- ${%\fInumber\fR}
- Substitutes the number of characters in $argv[\fInumber\fR]. (+)
- .TP 8
- $?
- Equivalent to `$status'. (+)
- .TP 8
- $$
- Substitutes the (decimal) process number of the (parent) shell.
- .TP 8
- $!
- Substitutes the (decimal) process number of the last
- background process started by this shell. (+)
- .TP 8
- $_
- Substitutes the command line of the last command executed. (+)
- .TP 8
- $<
- Substitutes a line from the standard input, with no further interpretation
- thereafter. It can be used to read from the keyboard in a shell script.
- (+) While \fIcsh\fR always quotes $<, as if it were equivalent to `$<:q',
- \fItcsh\fR does not. Furthermore, when \fItcsh\fR is waiting for a line to be
- typed the user may type an interrupt to interrupt the sequence into
- which the line is to be substituted, but \fIcsh\fR does not allow this.
- .PD
- .PP
- The editor command \fIexpand-variables\fR, normally bound to `^X-$',
- can be used to interactively expand individual variables.
- .SS "Command, filename and directory stack substitution"
- The remaining substitutions are applied selectively to the arguments of builtin
- commands. This means that portions of expressions which are not evaluated are
- not subjected to these expansions. For commands which are not internal to the
- shell, the command name is substituted separately from the argument list. This
- occurs very late, after input-output redirection is performed, and in a child
- of the main shell.
- .SS "Command substitution"
- Command substitution is indicated by a command enclosed in ``'. The output
- from such a command is broken into separate words at blanks, tabs and newlines,
- and null words are discarded. The output is variable and command substituted
- and put in place of the original string.
- .PP
- Command substitutions inside double
- quotes (`"') retain blanks and tabs; only newlines force new words. The single
- final newline does not force a new word in any case. It is thus possible for a
- command substitution to yield only part of a word, even if the command outputs
- a complete line.
- .PP
- By default, the shell since version 6.12 replaces all newline and carriage
- return characters in the command by spaces. If this is switched off by
- unsetting \fBcsubstnonl\fR, newlines separate commands as usual.
- .SS "Filename substitution"
- If a word contains any of the characters `*', `?', `[' or `{' or begins with
- the character `~' it is a candidate for filename substitution, also known as
- ``globbing''. This word is then regarded as a pattern (``glob-pattern''), and
- replaced with an alphabetically sorted list of file names which match the
- pattern.
- .PP
- In matching filenames, the character `.' at the beginning of a filename or
- immediately following a `/', as well as the character `/' must be matched
- explicitly (unless either
- .B globdot
- or
- .B globstar
- or both are set(+)). The character `*' matches any string of characters,
- including the null string. The character `?' matches any single character.
- The sequence `[...]' matches any one of the characters enclosed.
- Within `[...]', a pair of
- characters separated by `\-' matches any character lexically between the two.
- .PP
- (+) Some glob-patterns can be negated:
- The sequence `[^...]' matches any single character \fInot\fR specified by the
- characters and/or ranges of characters in the braces.
- .PP
- An entire glob-pattern can also be negated with `^':
- .IP "" 4
- > echo *
- .br
- bang crash crunch ouch
- .br
- > echo ^cr*
- .br
- bang ouch
- .PP
- Glob-patterns which do not use `?', `*', or `[]' or which use `{}' or `~'
- (below) are not negated correctly.
- .PP
- The metanotation `a{b,c,d}e' is a shorthand for `abe ace ade'.
- Left-to-right order is preserved: `/usr/source/s1/{oldls,ls}.c' expands
- to `/usr/source/s1/oldls.c /usr/source/s1/ls.c'. The results of matches are
- sorted separately at a low level to preserve this order:
- `../{memo,*box}' might expand to `../memo ../box ../mbox'.
- (Note that `memo' was not sorted with the results of matching `*box'.)
- It is not an error when this construct expands to files which do not exist,
- but it is possible to get an error from a command to which the expanded list
- is passed.
- This construct may be nested.
- As a special case the words `{', `}' and `{}' are passed undisturbed.
- .PP
- The character `~' at the beginning of a filename refers to home directories.
- Standing alone, i.e., `~', it expands to the invoker's home directory as
- reflected in the value of the \fBhome\fR shell variable. When followed by a
- name consisting of letters, digits and `\-' characters the shell searches for a
- user with that name and substitutes their home directory; thus `~ken' might
- expand to `/usr/ken' and `~ken/chmach' to `/usr/ken/chmach'. If the character
- `~' is followed by a character other than a letter or `/' or appears elsewhere
- than at the beginning of a word, it is left undisturbed.
- A command like `setenv MANPATH /usr/man:/usr/local/man:~/lib/man' does not,
- therefore, do home directory substitution as one might hope.
- .PP
- It is an error for a glob-pattern containing `*', `?', `[' or `~', with or
- without `^', not to match any files. However, only one pattern in a list of
- glob-patterns must match a file (so that, e.g., `rm *.a *.c *.o' would fail
- only if there were no files in the current directory ending in `.a', `.c', or
- `.o'), and if the \fBnonomatch\fR shell variable is set a pattern (or list
- of patterns) which matches nothing is left unchanged rather than causing
- an error.
- .PP
- The \fBglobstar\fR shell variable can be set to allow `**' or `***' as
- a file glob pattern that matches any string of characters including `/',
- recursively traversing any existing sub-directories. For example,
- `ls **.c' will list all the .c files in the current directory tree.
- If used by itself, it will match match zero or more sub-directories
- (e.g. `ls /usr/include/**/time.h' will list any file named `time.h'
- in the /usr/include directory tree; `ls /usr/include/**time.h' will match
- any file in the /usr/include directory tree ending in `time.h'; and
- `ls /usr/include/**time**.h' will match any .h file with `time' either
- in a subdirectory name or in the filename itself).
- To prevent problems with recursion, the `**' glob-pattern will not
- descend into a symbolic link containing a directory. To override this,
- use `***' (+)
- .PP
- The \fBnoglob\fR shell variable can be set to prevent filename substitution,
- and the \fIexpand-glob\fR editor command, normally bound to `^X-*', can be
- used to interactively expand individual filename substitutions.
- .SS "Directory stack substitution (+)"
- The directory stack is a list of directories, numbered from zero, used by the
- \fIpushd\fR, \fIpopd\fR and \fIdirs\fR builtin commands (q.v.).
- \fIdirs\fR can print, store in a file, restore and clear the directory stack
- at any time, and the \fBsavedirs\fR and \fBdirsfile\fR shell variables can be set to
- store the directory stack automatically on logout and restore it on login.
- The \fBdirstack\fR shell variable can be examined to see the directory stack and
- set to put arbitrary directories into the directory stack.
- .PP
- The character `=' followed by one or more digits expands to an entry in
- the directory stack. The special case `=\-' expands to the last directory in
- the stack. For example,
- .IP "" 4
- > dirs \-v
- .br
- 0 /usr/bin
- .br
- 1 /usr/spool/uucp
- .br
- 2 /usr/accts/sys
- .br
- > echo =1
- .br
- /usr/spool/uucp
- .br
- > echo =0/calendar
- .br
- /usr/bin/calendar
- .br
- > echo =\-
- .br
- /usr/accts/sys
- .PP
- The \fBnoglob\fR and \fBnonomatch\fR shell variables and the \fIexpand-glob\fR
- editor command apply to directory stack as well as filename substitutions.
- .SS "Other substitutions (+)"
- There are several more transformations involving filenames, not strictly
- related to the above but mentioned here for completeness.
- \fIAny\fR filename may be expanded to a full path when the
- \fBsymlinks\fR variable (q.v.) is set to `expand'.
- Quoting prevents this expansion, and
- the \fInormalize-path\fR editor command does it on demand.
- The \fInormalize-command\fR editor command expands commands in PATH into
- full paths on demand.
- Finally, \fIcd\fR and \fIpushd\fR interpret `\-' as the old working directory
- (equivalent to the shell variable \fBowd\fR).
- This is not a substitution at all, but an abbreviation recognized by only
- those commands. Nonetheless, it too can be prevented by quoting.
- .SS Commands
- The next three sections describe how the shell executes commands and
- deals with their input and output.
- .SS Simple commands, pipelines and sequences
- A simple command is a sequence of words, the first of which specifies the
- command to be executed. A series of simple commands joined by `|' characters
- forms a pipeline. The output of each command in a pipeline is connected to the
- input of the next.
- .PP
- Simple commands and pipelines may be joined into sequences with `;', and will
- be executed sequentially. Commands and pipelines can also be joined into
- sequences with `||' or `&&', indicating, as in the C language, that the second
- is to be executed only if the first fails or succeeds respectively.
- .PP
- A simple command, pipeline or sequence may be placed in parentheses, `()',
- to form a simple command, which may in turn be a component of a pipeline or
- sequence. A command, pipeline or sequence can be executed
- without waiting for it to terminate by following it with an `&'.
- .SS "Builtin and non-builtin command execution"
- Builtin commands are executed within the shell. If any component of a
- pipeline except the last is a builtin command, the pipeline is executed
- in a subshell.
- .PP
- Parenthesized commands are always executed in a subshell.
- .IP "" 4
- (cd; pwd); pwd
- .PP
- thus prints the \fBhome\fR directory, leaving you where you were
- (printing this after the home directory), while
- .IP "" 4
- cd; pwd
- .PP
- leaves you in the \fBhome\fR directory. Parenthesized commands are most often
- used to prevent \fIcd\fR from affecting the current shell.
- .PP
- When a command to be executed is found not to be a builtin command the shell
- attempts to execute the command via \fIexecve\fR(2). Each word in the variable
- \fBpath\fR names a directory in which the shell will look for the
- command. If the shell is not given a \fB\-f\fR option, the shell
- hashes the names in these directories into an internal table so that it will
- try an \fIexecve\fR(2) in only a directory where there is a possibility that the
- command resides there. This greatly speeds command location when a large
- number of directories are present in the search path. This hashing mechanism is
- not used:
- .TP 4
- .B 1.
- If hashing is turned explicitly off via \fIunhash\fR.
- .TP 4
- .B 2.
- If the shell was given a \fB\-f\fR argument.
- .TP 4
- .B 3.
- For each directory component of \fBpath\fR which does not begin with a `/'.
- .TP 4
- .B 4.
- If the command contains a `/'.
- .PP
- In the above four cases the shell concatenates each component of the path
- vector with the given command name to form a path name of a file which it
- then attempts to execute it. If execution is successful, the search stops.
- .PP
- If the file has execute permissions but is not an executable to the system
- (i.e., it is neither an executable binary nor a script that specifies its
- interpreter), then it is assumed to be a file containing shell commands and
- a new shell is spawned to read it. The \fIshell\fR special alias may be set
- to specify an interpreter other than the shell itself.
- .PP
- On systems which do not understand the `#!' script interpreter convention
- the shell may be compiled to emulate it; see the \fBversion\fR shell
- variable. If so, the shell checks the first line of the file to
- see if it is of the form `#!\fIinterpreter\fR \fIarg\fR ...'. If it is,
- the shell starts \fIinterpreter\fR with the given \fIarg\fRs and feeds the
- file to it on standard input.
- .SS Input/output
- The standard input and standard output of a command may be redirected with the
- following syntax:
- .PP
- .PD 0
- .TP 8
- < \fIname
- Open file \fIname\fR (which is first variable, command and filename
- expanded) as the standard input.
- .TP 8
- << \fIword
- Read the shell input up to a line which is identical to \fIword\fR. \fIword\fR
- is not subjected to variable, filename or command substitution, and each input
- line is compared to \fIword\fR before any substitutions are done on this input
- line. Unless a quoting `\e', `"', `' or ``' appears in \fIword\fR variable and
- command substitution is performed on the intervening lines, allowing `\e' to
- quote `$', `\e' and ``'. Commands which are substituted have all blanks, tabs,
- and newlines preserved, except for the final newline which is dropped. The
- resultant text is placed in an anonymous temporary file which is given to the
- command as standard input.
- .PP
- > \fIname
- .br
- >! \fIname
- .br
- >& \fIname
- .TP 8
- >&! \fIname
- The file \fIname\fR is used as standard output. If the file does not exist
- then it is created; if the file exists, it is truncated, its previous contents
- being lost.
- .RS +8
- .PD
- .PP
- If the shell variable \fBnoclobber\fR is set, then the file must not exist or be a
- character special file (e.g., a terminal or `/dev/null') or an error results.
- This helps prevent accidental destruction of files. In this case the `!' forms
- can be used to suppress this check.
- .PP
- The forms involving `&' route the diagnostic output into the specified file as
- well as the standard output. \fIname\fR is expanded in the same way as `<'
- input filenames are.
- .PD 0
- .RE
- .PP
- >> \fIname
- .br
- >>& \fIname
- .br
- >>! \fIname
- .TP 8
- >>&! \fIname
- Like `>', but appends output to the end of \fIname\fR.
- If the shell variable \fBnoclobber\fR is set, then it is an error for
- the file \fInot\fR to exist, unless one of the `!' forms is given.
- .PD
- .PP
- A command receives the environment in which the shell was invoked as modified
- by the input-output parameters and the presence of the command in a pipeline.
- Thus, unlike some previous shells, commands run from a file of shell commands
- have no access to the text of the commands by default; rather they receive the
- original standard input of the shell. The `<<' mechanism should be used to
- present inline data. This permits shell command scripts to function as
- components of pipelines and allows the shell to block read its input. Note
- that the default standard input for a command run detached is \fInot\fR
- the empty file \fI/dev/null\fR, but the original standard input of the shell.
- If this is a terminal and if the process attempts to read from the terminal,
- then the process will block and the user will be notified (see \fBJobs\fR).
- .PP
- Diagnostic output may be directed through a pipe with the standard output.
- Simply use the form `|&' rather than just `|'.
- .PP
- The shell cannot presently redirect diagnostic output without also redirecting
- standard output, but `(\fIcommand\fR > \fIoutput-file\fR) >& \fIerror-file\fR'
- is often an acceptable workaround. Either \fIoutput-file\fR or
- \fIerror-file\fR may be `/dev/tty' to send output to the terminal.
- .SS Features
- Having described how the shell accepts, parses and executes
- command lines, we now turn to a variety of its useful features.
- .SS "Control flow"
- The shell contains a number of commands which can be used to regulate the
- flow of control in command files (shell scripts) and (in limited but
- useful ways) from terminal input. These commands all operate by forcing the
- shell to reread or skip in its input and, due to the implementation,
- restrict the placement of some of the commands.
- .PP
- The \fIforeach\fR, \fIswitch\fR, and \fIwhile\fR statements, as well as the
- \fIif-then-else\fR form of the \fIif\fR statement, require that the major
- keywords appear in a single simple command on an input line as shown below.
- .PP
- If the shell's input is not seekable, the shell buffers up input whenever
- a loop is being read and performs seeks in this internal buffer to
- accomplish the rereading implied by the loop. (To the extent that this
- allows, backward \fIgoto\fRs will succeed on non-seekable inputs.)
- .SS Expressions
- The \fIif\fR, \fIwhile\fR and \fIexit\fR builtin commands
- use expressions with a common syntax. The expressions can include any
- of the operators described in the next three sections. Note that the \fI@\fR
- builtin command (q.v.) has its own separate syntax.
- .SS "Logical, arithmetical and comparison operators"
- These operators are similar to those of C and have the same precedence.
- They include
- .IP "" 4
- || && | ^ & == != =~ !~ <= >=
- .br
- < > << >> + \- * / % ! ~ ( )
- .PP
- Here the precedence increases to the right, `==' `!=' `=~' and `!~', `<='
- `>=' `<' and `>', `<<' and `>>', `+' and `\-', `*' `/' and `%' being, in
- groups, at the same level. The `==' `!=' `=~' and `!~' operators compare
- their arguments as strings; all others operate on numbers. The operators
- `=~' and `!~' are like `!=' and `==' except that the right hand side is a
- glob-pattern (see \fBFilename substitution\fR) against which the left hand
- operand is matched. This reduces the need for use of the \fIswitch\fR
- builtin command in shell scripts when all that is really needed is
- pattern matching.
- .PP
- Null or
- missing arguments are considered `0'. The results of all expressions are
- strings, which represent decimal numbers. It is important to note that
- no two components of an expression can appear in the same word; except
- when adjacent to components of expressions which are syntactically
- significant to the parser (`&' `|' `<' `>' `(' `)') they should be
- surrounded by spaces.
- .SS "Command exit status"
- Commands can be executed in expressions and their exit status
- returned by enclosing them in braces (`{}'). Remember that the braces should
- be separated from the words of the command by spaces. Command executions
- succeed, returning true, i.e., `1', if the command exits with status 0,
- otherwise they fail, returning false, i.e., `0'. If more detailed status
- information is required then the command should be executed outside of an
- expression and the \fBstatus\fR shell variable examined.
- .SS "File inquiry operators"
- Some of these operators perform true/false tests on files and related
- objects. They are of the form \fB\-\fIop file\fR, where \fIop\fR is one of
- .PP
- .PD 0
- .RS +4
- .TP 4
- .B r
- Read access
- .TP 4
- .B w
- Write access
- .TP 4
- .B x
- Execute access
- .TP 4
- .B X
- Executable in the path or shell builtin, e.g., `\-X ls' and `\-X ls\-F' are
- generally true, but `\-X /bin/ls' is not (+)
- .TP 4
- .B e
- Existence
- .TP 4
- .B o
- Ownership
- .TP 4
- .B z
- Zero size
- .TP 4
- .B s
- Non-zero size (+)
- .TP 4
- .B f
- Plain file
- .TP 4
- .B d
- Directory
- .TP 4
- .B l
- Symbolic link (+) *
- .TP 4
- .B b
- Block special file (+)
- .TP 4
- .B c
- Character special file (+)
- .TP 4
- .B p
- Named pipe (fifo) (+) *
- .TP 4
- .B S
- Socket special file (+) *
- .TP 4
- .B u
- Set-user-ID bit is set (+)
- .TP 4
- .B g
- Set-group-ID bit is set (+)
- .TP 4
- .B k
- Sticky bit is set (+)
- .TP 4
- .B t
- \fIfile\fR (which must be a digit) is an open file descriptor
- for a terminal device (+)
- .TP 4
- .B R
- Has been migrated (Convex only) (+)
- .TP 4
- .B L
- Applies subsequent operators in a multiple-operator test to a symbolic link
- rather than to the file to which the link points (+) *
- .RE
- .PD
- .PP
- \fIfile\fR is command and filename expanded and then tested to
- see if it has the specified relationship to the real user. If \fIfile\fR
- does not exist or is inaccessible or, for the operators indicated by `*',
- if the specified file type does not exist on the current system,
- then all enquiries return false, i.e., `0'.
- .PP
- These operators may be combined for conciseness: `\-\fIxy file\fR' is
- equivalent to `\-\fIx file\fR && \-\fIy file\fR'. (+) For example, `\-fx' is true
- (returns `1') for plain executable files, but not for directories.
- .PP
- \fBL\fR may be used in a multiple-operator test to apply subsequent operators
- to a symbolic link rather than to the file to which the link points.
- For example, `\-lLo' is true for links owned by the invoking user.
- \fBLr\fR, \fBLw\fR and \fBLx\fR are always true for links and false for
- non-links. \fBL\fR has a different meaning when it is the last operator
- in a multiple-operator test; see below.
- .PP
- It is possible but not useful, and sometimes misleading, to combine operators
- which expect \fIfile\fR to be a file with operators which do not
- (e.g., \fBX\fR and \fBt\fR). Following \fBL\fR with a non-file operator
- can lead to particularly strange results.
- .PP
- Other operators return other information, i.e., not just `0' or `1'. (+)
- They have the same format as before; \fIop\fR may be one of
- .PP
- .PD 0
- .RS +4
- .TP 8
- .B A
- Last file access time, as the number of seconds since the epoch
- .TP 8
- .B A:
- Like \fBA\fR, but in timestamp format, e.g., `Fri May 14 16:36:10 1993'
- .TP 8
- .B M
- Last file modification time
- .TP 8
- .B M:
- Like \fBM\fR, but in timestamp format
- .TP 8
- .B C
- Last inode modification time
- .TP 8
- .B C:
- Like \fBC\fR, but in timestamp format
- .TP 8
- .B D
- Device number
- .TP 8
- .B I
- Inode number
- .TP 8
- .B F
- Composite \fBf\fRile identifier, in the form \fIdevice\fR:\fIinode\fR
- .TP 8
- .B L
- The name of the file pointed to by a symbolic link
- .TP 8
- .B N
- Number of (hard) links
- .TP 8
- .B P
- Permissions, in octal, without leading zero
- .TP 8
- .B P:
- Like \fBP\fR, with leading zero
- .TP 8
- .B P\fImode
- Equivalent to `\-P \fIfile\fR & \fImode\fR', e.g., `\-P22 \fIfile\fR' returns
- `22' if \fIfile\fR is writable by group and other, `20' if by group only,
- and `0' if by neither
- .TP 8
- .B P\fImode\fB:
- Like \fBP\fImode\fR, with leading zero
- .TP 8
- .B U
- Numeric userid
- .TP 8
- .B U:
- Username, or the numeric userid if the username is unknown
- .TP 8
- .B G
- Numeric groupid
- .TP 8
- .B G:
- Groupname, or the numeric groupid if the groupname is unknown
- .TP 8
- .B Z
- Size, in bytes
- .RE
- .PD
- .PP
- Only one of these operators may appear in a multiple-operator test, and it
- must be the last. Note that \fBL\fR has a different meaning at the end of and
- elsewhere in a multiple-operator test. Because `0' is a valid return value
- for many of these operators, they do not return `0' when they fail: most
- return `\-1', and \fBF\fR returns `:'.
- .PP
- If the shell is compiled with POSIX defined (see the \fBversion\fR shell
- variable), the result of a file inquiry is based on the permission bits of
- the file and not on the result of the \fIaccess\fR(2) system call.
- For example, if one tests a file with \fB\-w\fR whose permissions would
- ordinarily allow writing but which is on a file system mounted read-only,
- the test will succeed in a POSIX shell but fail in a non-POSIX shell.
- .PP
- File inquiry operators can also be evaluated with the \fIfiletest\fR builtin
- command (q.v.) (+).
- .SS Jobs
- The shell associates a \fIjob\fR with each pipeline. It keeps a table of
- current jobs, printed by the \fIjobs\fR command, and assigns them small integer
- numbers. When a job is started asynchronously with `&', the shell prints a
- line which looks like
- .IP "" 4
- [1] 1234
- .PP
- indicating that the job which was started asynchronously was job number 1 and
- had one (top-level) process, whose process id was 1234.
- .PP
- If you are running a job and wish to do something else you may hit the suspend
- key (usually `^Z'),
- which sends a STOP signal to the current job. The shell will then normally
- indicate that the job has been `Suspended' and print another prompt.
- If the \fBlistjobs\fR shell variable is set, all jobs will be listed
- like the \fIjobs\fR builtin command; if it is set to `long' the listing will
- be in long format, like `jobs \-l'.
- You can then manipulate the state of the suspended job.
- You can put it in the
- ``background'' with the \fIbg\fR command or run some other commands and
- eventually bring the job back into the ``foreground'' with \fIfg\fR.
- (See also the \fIrun-fg-editor\fR editor command.)
- A `^Z' takes effect immediately and is like an interrupt
- in that pending output and unread input are discarded when it is typed.
- The \fIwait\fR builtin command causes the shell to wait for all background
- jobs to complete.
- .PP
- The `^]' key sends a delayed suspend signal, which does not generate a STOP
- signal until a program attempts to \fIread\fR(2) it, to the current job.
- This can usefully be typed ahead when you have prepared some commands for a
- job which you wish to stop after it has read them.
- The `^Y' key performs this function in \fIcsh\fR(1); in \fItcsh\fR,
- `^Y' is an editing command. (+)
- .PP
- A job being run in the background stops if it tries to read from the
- terminal. Background jobs are normally allowed to produce output, but this can
- be disabled by giving the command `stty tostop'. If you set this tty option,
- then background jobs will stop when they try to produce output like they do
- when they try to read input.
- .PP
- There are several ways to refer to jobs in the shell. The character `%'
- introduces a job name. If you wish to refer to job number 1, you can name it
- as `%1'. Just naming a job brings it to the foreground; thus `%1' is a synonym
- for `fg %1', bringing job 1 back into the foreground. Similarly, saying `%1 &'
- resumes job 1 in the background, just like `bg %1'. A job can also be named
- by an unambiguous prefix of the string typed in to start it: `%ex' would
- normally restart a suspended \fIex\fR(1) job, if there were only one suspended
- job whose name began with the string `ex'. It is also possible to say
- `%?\fIstring\fR' to specify a job whose text contains \fIstring\fR, if there
- is only one such job.
- .PP
- The shell maintains a notion of the current and previous jobs. In output
- pertaining to jobs, the current job is marked with a `+' and the previous job
- with a `\-'. The abbreviations `%+', `%', and (by analogy with the syntax of
- the \fIhistory\fR mechanism) `%%' all refer to the current job, and `%\-' refers
- to the previous job.
- .PP
- The job control mechanism requires that the \fIstty\fR(1) option `new' be set
- on some systems. It is an artifact from a `new' implementation of the tty
- driver which allows generation of interrupt characters from the keyboard to
- tell jobs to stop. See \fIstty\fR(1) and the \fIsetty\fR builtin command for
- details on setting options in the new tty driver.
- .SS "Status reporting"
- The shell learns immediately whenever a process changes state. It normally
- informs you whenever a job becomes blocked so that no further progress is
- possible, but only right before it prints a prompt. This is done so that it
- does not otherwise disturb your work. If, however, you set the shell variable
- \fBnotify\fR, the shell will notify you immediately of changes of status in
- background jobs. There is also a shell command \fInotify\fR which marks a
- single process so that its status changes will be immediately reported. By
- default \fInotify\fR marks the current process; simply say `notify' after
- starting a background job to mark it.
- .PP
- When you try to leave the shell while jobs are stopped, you will be
- warned that `There are suspended jobs.' You may use the \fIjobs\fR command to
- see what they are. If you do this or immediately try to exit again, the shell
- will not warn you a second time, and the suspended jobs will be terminated.
- .SS "Automatic, periodic and timed events (+)"
- There are various ways to run commands and take other actions automatically
- at various times in the ``life cycle'' of the shell. They are summarized here,
- and described in detail under the appropriate \fBBuiltin commands\fR,
- \fBSpecial shell variables\fR and \fBSpecial aliases\fR.
- .PP
- The \fIsched\fR builtin command puts commands in a scheduled-event list,
- to be executed by the shell at a given time.
- .PP
- The \fIbeepcmd\fR, \fIcwdcmd\fR, \fIperiodic\fR, \fIprecmd\fR, \fIpostcmd\fR,
- and \fIjobcmd\fR
- \fBSpecial aliases\fR can be set, respectively, to execute commands when the shell wants
- to ring the bell, when the working directory changes, every \fBtperiod\fR
- minutes, before each prompt, before each command gets executed, after each
- command gets executed, and when a job is started or is brought into the
- foreground.
- .PP
- The \fBautologout\fR shell variable can be set to log out or lock the shell
- after a given number of minutes of inactivity.
- .PP
- The \fBmail\fR shell variable can be set to check for new mail periodically.
- .PP
- The \fBprintexitvalue\fR shell variable can be set to print the exit status
- of commands which exit with a status other than zero.
- .PP
- The \fBrmstar\fR shell variable can be set to ask the user, when `rm *' is
- typed, if that is really what was meant.
- .PP
- The \fBtime\fR shell variable can be set to execute the \fItime\fR builtin
- command after the completion of any process that takes more than a given
- number of CPU seconds.
- .PP
- The \fBwatch\fR and \fBwho\fR shell variables can be set to report when
- selected users log in or out, and the \fIlog\fR builtin command reports
- on those users at any time.
- .SS "Native Language System support (+)"
- The shell is eight bit clean
- (if so compiled; see the \fBversion\fR shell variable)
- and thus supports character sets needing this capability.
- NLS support differs depending on whether or not
- the shell was compiled to use the system's NLS (again, see \fBversion\fR).
- In either case, 7-bit ASCII is the default character code
- (e.g., the classification of which characters are printable) and sorting,
- and changing the \fBLANG\fR or \fBLC_CTYPE\fR environment variables
- causes a check for possible changes in these respects.
- .PP
- When using the system's NLS, the \fIsetlocale\fR(3) function is called
- to determine appropriate character code/classification and sorting
- (e.g., a 'en_CA.UTF-8' would yield "UTF-8" as a character code).
- This function typically examines the \fBLANG\fR and \fBLC_CTYPE\fR
- environment variables; refer to the system documentation for further details.
- When not using the system's NLS, the shell simulates it by assuming that the
- ISO 8859-1 character set is used
- whenever either of the \fBLANG\fR and \fBLC_CTYPE\fR variables are set, regardless of
- their values. Sorting is not affected for the simulated NLS.
- .PP
- In addition, with both real and simulated NLS, all printable
- characters in the range \e200\-\e377, i.e., those that have
- M-\fIchar\fR bindings, are automatically rebound to \fIself-insert-command\fR.
- The corresponding binding for the escape-\fIchar\fR sequence, if any, is
- left alone.
- These characters are not rebound if the \fBNOREBIND\fR environment variable
- is set. This may be useful for the simulated NLS or a primitive real NLS
- which assumes full ISO 8859-1. Otherwise, all M-\fIchar\fR bindings in the
- range \e240\-\e377 are effectively undone.
- Explicitly rebinding the relevant keys with \fIbindkey\fR
- is of course still possible.
- .PP
- Unknown characters (i.e., those that are neither printable nor control
- characters) are printed in the format \ennn.
- If the tty is not in 8 bit mode, other 8 bit characters are printed by
- converting them to ASCII and using standout mode. The shell
- never changes the 7/8 bit mode of the tty and tracks user-initiated
- changes of 7/8 bit mode. NLS users (or, for that matter, those who want to
- use a meta key) may need to explicitly set
- the tty in 8 bit mode through the appropriate \fIstty\fR(1)
- command in, e.g., the \fI~/.login\fR file.
- .SS "OS variant support (+)"
- A number of new builtin commands are provided to support features in
- particular operating systems. All are described in detail in the
- \fBBuiltin commands\fR section.
- .PP
- On systems that support TCF (aix-ibm370, aix-ps2),
- \fIgetspath\fR and \fIsetspath\fR get and set the system execution path,
- \fIgetxvers\fR and \fIsetxvers\fR get and set the experimental version prefix
- and \fImigrate\fR migrates processes between sites. The \fIjobs\fR builtin
- prints the site on which each job is executing.
- .PP
- Under BS2000, \fIbs2cmd\fR executes commands of the underlying BS2000/OSD
- operating system.
- .PP
- Under Domain/OS, \fIinlib\fR adds shared libraries to the current environment,
- \fIrootnode\fR changes the rootnode and \fIver\fR changes the systype.
- .PP
- Under Mach, \fIsetpath\fR is equivalent to Mach's \fIsetpath\fR(1).
- .PP
- Under Masscomp/RTU and Harris CX/UX, \fIuniverse\fR sets the universe.
- .PP
- Under Harris CX/UX, \fIucb\fR or \fIatt\fR runs a command under the specified
- universe.
- .PP
- Under Convex/OS, \fIwarp\fR prints or sets the universe.
- .PP
- The \fBVENDOR\fR, \fBOSTYPE\fR and \fBMACHTYPE\fR environment variables
- indicate respectively the vendor, operating system and machine type
- (microprocessor class or machine model) of the
- system on which the shell thinks it is running.
- These are particularly useful when sharing one's home directory between several
- types of machines; one can, for example,
- .IP "" 4
- set path = (~/bin.$MACHTYPE /usr/ucb /bin /usr/bin .)
- .PP
- in one's \fI~/.login\fR and put executables compiled for each machine in the
- appropriate directory.
- .PP
- The \fBversion\fR shell
- variable indicates what options were chosen when the shell was compiled.
- .PP
- Note also the \fInewgrp\fR builtin, the \fBafsuser\fR and
- \fBecho_style\fR shell variables and the system-dependent locations of
- the shell's input files (see \fBFILES\fR).
- .SS "Signal handling"
- Login shells ignore interrupts when reading the file \fI~/.logout\fR.
- The shell ignores quit signals unless started with \fB\-q\fR.
- Login shells catch the terminate signal, but non-login shells inherit the
- terminate behavior from their parents.
- Other signals have the values which the shell inherited from its parent.
- .PP
- In shell scripts, the shell's handling of interrupt and terminate signals
- can be controlled with \fIonintr\fR, and its handling of hangups can be
- controlled with \fIhup\fR and \fInohup\fR.
- .PP
- The shell exits on a hangup (see also the \fBlogout\fR shell variable). By
- default, the shell's children do too, but the shell does not send them a
- hangup when it exits. \fIhup\fR arranges for the shell to send a hangup to
- a child when it exits, and \fInohup\fR sets a child to ignore hangups.
- .SS "Terminal management (+)"
- The shell uses three different sets of terminal (``tty'') modes:
- `edit', used when editing, `quote', used when quoting literal characters,
- and `execute', used when executing commands.
- The shell holds some settings in each mode constant, so commands which leave
- the tty in a confused state do not interfere with the shell.
- The shell also matches changes in the speed and padding of the tty.
- The list of tty modes that are kept constant
- can be examined and modified with the \fIsetty\fR builtin.
- Note that although the editor uses CBREAK mode (or its equivalent),
- it takes typed-ahead characters anyway.
- .PP
- The \fIechotc\fR, \fIsettc\fR and \fItelltc\fR commands can be used to
- manipulate and debug terminal capabilities from the command line.
- .PP
- On systems that support SIGWINCH or SIGWINDOW, the shell
- adapts to window resizing automatically and adjusts the environment
- variables \fBLINES\fR and \fBCOLUMNS\fR if set. If the environment
- variable \fBTERMCAP\fR contains li# and co# fields, the shell adjusts
- them to reflect the new window size.
- .SH REFERENCE
- The next sections of this manual describe all of the available
- \fBBuiltin commands\fR, \fBSpecial aliases\fR and
- \fBSpecial shell variables\fR.
- .SS "Builtin commands"
- .TP 8
- .B %\fIjob
- A synonym for the \fIfg\fR builtin command.
- .TP 8
- .B %\fIjob \fB&
- A synonym for the \fIbg\fR builtin command.
- .TP 8
- .B :
- Does nothing, successfully.
- .PP
- .B @
- .br
- .B @ \fIname\fB = \fIexpr
- .br
- .B @ \fIname\fR[\fIindex\fR]\fB = \fIexpr
- .br
- .B @ \fIname\fB++\fR|\fB--
- .PD 0
- .TP 8
- .B @ \fIname\fR[\fIindex\fR]\fB++\fR|\fB--
- The first form prints the values of all shell variables.
- .PD
- .RS +8
- .PP
- The second form assigns the value of \fIexpr\fR to \fIname\fR.
- The third form assigns the value of \fIexpr\fR to the \fIindex\fR'th
- component of \fIname\fR; both \fIname\fR and its \fIindex\fR'th component
- must already exist.
- .PP
- \fIexpr\fR may contain the operators `*', `+', etc., as in C.
- If \fIexpr\fR contains `<', `>', `&' or `' then at least that part of
- \fIexpr\fR must be placed within `()'.
- Note that the syntax of \fIexpr\fR has nothing to do with that described
- under \fBExpressions\fR.
- .PP
- The fourth and fifth forms increment (`++') or decrement (`\-\-') \fIname\fR
- or its \fIindex\fR'th component.
- .PP
- The space between `@' and \fIname\fR is required. The spaces between
- \fIname\fR and `=' and between `=' and \fIexpr\fR are optional. Components of
- \fIexpr\fR must be separated by spaces.
- .RE
- .PD
- .TP 8
- .B alias \fR[\fIname \fR[\fIwordlist\fR]]
- Without arguments, prints all aliases.
- With \fIname\fR, prints the alias for name.
- With \fIname\fR and \fIwordlist\fR, assigns
- \fIwordlist\fR as the alias of \fIname\fR.
- \fIwordlist\fR is command and filename substituted.
- \fIname\fR may not be `alias' or `unalias'.
- See also the \fIunalias\fR builtin command.
- .TP 8
- .B alloc
- Shows the amount of dynamic memory acquired, broken down into used and free
- memory. With an argument shows the number of free and used blocks in each size
- category. The categories start at size 8 and double at each step. This
- command's output may vary across system types, because systems other than the VAX
- may use a different memory allocator.
- .TP 8
- .B bg \fR[\fB%\fIjob\fR ...]
- Puts the specified jobs (or, without arguments, the current job)
- into the background, continuing each if it is stopped.
- \fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
- under \fBJobs\fR.
- .PP
- .B bindkey \fR[\fB\-l\fR|\fB\-d\fR|\fB\-e\fR|\fB\-v\fR|\fB\-u\fR] (+)
- .br
- \fBbindkey \fR[\fB\-a\fR] [\fB\-b\fR] [\fB\-k\fR] [\fB\-r\fR] [\fB\-\-\fR] \fIkey \fR(+)
- .PD 0
- .TP 8
- \fBbindkey \fR[\fB\-a\fR] [\fB\-b\fR] [\fB\-k\fR] [\fB\-c\fR|\fB\-s\fR] [\fB\-\-\fR] \fIkey command \fR(+)
- .\" .B macro can't take too many words, so I used \fB in the previous tags
- Without options, the first form lists all bound keys and the editor command to which each is bound,
- the second form lists the editor command to which \fIkey\fR is bound and
- the third form binds the editor command \fIcommand\fR to \fIkey\fR.
- Options include:
- .PD
- .PP
- .PD 0
- .RS +8
- .TP 4
- .B \-l
- Lists all editor commands and a short description of each.
- .TP 4
- .B \-d
- Binds all keys to the standard bindings for the default editor.
- .TP 4
- .B \-e
- Binds all keys to the standard GNU Emacs-like bindings.
- .TP 4
- .B \-v
- Binds all keys to the standard \fIvi\fR(1)-like bindings.
- .TP 4
- .B \-a
- Lists or changes key-bindings in the alternative key map.
- This is the key map used in \fIvi\fR command mode.
- .TP 4
- .B \-b
- \fIkey\fR is interpreted as
- a control character written ^\fIcharacter\fR (e.g., `^A') or
- C-\fIcharacter\fR (e.g., `C-A'),
- a meta character written M-\fIcharacter\fR (e.g., `M-A'),
- a function key written F-\fIstring\fR (e.g., `F-string'),
- or an extended prefix key written X-\fIcharacter\fR (e.g., `X-A').
- .TP 4
- .B \-k
- \fIkey\fR is interpreted as a symbolic arrow key name, which may be one of
- `down', `up', `left' or `right'.
- .TP 4
- .B \-r
- Removes \fIkey\fR's binding.
- Be careful: `bindkey \-r' does \fInot\fR bind \fIkey\fR to
- \fIself-insert-command\fR (q.v.), it unbinds \fIkey\fR completely.
- .TP 4
- .B \-c
- \fIcommand\fR is interpreted as a builtin or external command instead of an
- editor command.
- .TP 4
- .B \-s
- \fIcommand\fR is taken as a literal string and treated as terminal input
- when \fIkey\fR is typed. Bound keys in \fIcommand\fR are themselves
- reinterpreted, and this continues for ten levels of interpretation.
- .TP 4
- .B \-\-
- Forces a break from option processing, so the next word is taken as \fIkey\fR
- even if it begins with '\-'.
- .TP 4
- .B \-u \fR(or any invalid option)
- Prints a usage message.
- .PD
- .PP
- \fIkey\fR may be a single character or a string.
- If a command is bound to a string, the first character of the string is bound to
- \fIsequence-lead-in\fR and the entire string is bound to the command.
- .PP
- Control characters in \fIkey\fR can be literal (they can be typed by preceding
- them with the editor command \fIquoted-insert\fR, normally bound to `^V') or
- written caret-character style, e.g., `^A'. Delete is written `^?'
- (caret-question mark). \fIkey\fR and \fIcommand\fR can contain backslashed
- escape sequences (in the style of System V \fIecho\fR(1)) as follows:
- .RS +4
- .TP 8
- .PD 0
- .B \ea
- Bell
- .TP 8
- .B \eb
- Backspace
- .TP 8
- .B \ee
- Escape
- .TP 8
- .B \ef
- Form feed
- .TP 8
- .B \en
- Newline
- .TP 8
- .B \er
- Carriage return
- .TP 8
- .B \et
- Horizontal tab
- .TP 8
- .B \ev
- Vertical tab
- .TP 8
- .B \e\fInnn
- The ASCII character corresponding to the octal number \fInnn\fR
- .PD
- .RE
- .PP
- `\e' nullifies the special meaning of the following character, if it has
- any, notably `\\' and `^'.
- .RE
- .TP 8
- .B bs2cmd \fIbs2000-command\fR (+)
- Passes \fIbs2000-command\fR to the BS2000 command interpreter for
- execution. Only non-interactive commands can be executed, and it is
- not possible to execute any command that would overlay the image
- of the current process, like /EXECUTE or /CALL-PROCEDURE. (BS2000 only)
- .TP 8
- .B break
- Causes execution to resume after the \fIend\fR of the nearest
- enclosing \fIforeach\fR or \fIwhile\fR. The remaining commands on the
- current line are executed. Multi-level breaks are thus
- possible by writing them all on one line.
- .TP 8
- .B breaksw
- Causes a break from a \fIswitch\fR, resuming after the \fIendsw\fR.
- .TP 8
- .B builtins \fR(+)
- Prints the names of all builtin commands.
- .TP 8
- .B bye \fR(+)
- A synonym for the \fIlogout\fR builtin command.
- Available only if the shell was so compiled;
- see the \fBversion\fR shell variable.
- .TP 8
- .B case \fIlabel\fB:
- A label in a \fIswitch\fR statement as discussed below.
- .TP 8
- .B cd \fR[\fB\-p\fR] [\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR] [\I--\fR] [\fIname\fR]
- If a directory \fIname\fR is given, changes the shell's working directory
- to \fIname\fR. If not, changes to \fBhome\fR.
- If \fIname\fR is `\-' it is interpreted as the previous working directory
- (see \fBOther substitutions\fR). (+)
- If \fIname\fR is not a subdirectory of the current directory
- (and does not begin with `/', `./' or `../'), each component of the variable
- \fBcdpath\fR is checked to see if it has a subdirectory \fIname\fR. Finally, if
- all else fails but \fIname\fR is a shell variable whose value
- begins with `/', then this is tried to see if it is a directory.
- .RS +8
- .PP
- With \fB\-p\fR, prints the final directory stack, just like \fIdirs\fR.
- The \fB\-l\fR, \fB\-n\fR and \fB\-v\fR flags have the same effect on \fIcd\fR
- as on \fIdirs\fR, and they imply \fB\-p\fR. (+)
- Using \fB\-\-\fR forces a break from option processing so the next word
- is taken as the directory \fIname\fR even if it begins with '\-'. (+)
- .PP
- See also the \fBimplicitcd\fR shell variable.
- .RE
- .TP 8
- .B chdir
- A synonym for the \fIcd\fR builtin command.
- .TP 8
- .B complete \fR[\fIcommand\fR [\fIword\fB/\fIpattern\fB/\fIlist\fR[\fB:\fIselect\fR]\fB/\fR[[\fIsuffix\fR]\fB/\fR] ...]] (+)
- Without arguments, lists all completions.
- With \fIcommand\fR, lists completions for \fIcommand\fR.
- With \fIcommand\fR and \fIword\fR etc., defines completions.
- .RS +8
- .PP
- \fIcommand\fR may be a full command name or a glob-pattern
- (see \fBFilename substitution\fR). It can begin with `\-' to indicate that
- completion should be used only when \fIcommand\fR is ambiguous.
- .PP
- \fIword\fR specifies which word relative to the current word
- is to be completed, and may be one of the following:
- .PP
- .PD 0
- .RS +4
- .TP 4
- .B c
- Current-word completion.
- \fIpattern\fR is a glob-pattern which must match the beginning of the current word on
- the command line. \fIpattern\fR is ignored when completing the current word.
- .TP 4
- .B C
- Like \fBc\fR, but includes \fIpattern\fR when completing the current word.
- .TP 4
- .B n
- Next-word completion.
- \fIpattern\fR is a glob-pattern which must match the beginning of the previous word on
- the command line.
- .TP 4
- .B N
- Like \fBn\fR, but must match the beginning of the word two before the current word.
- .TP 4
- .B p
- Position-dependent completion.
- \fIpattern\fR is a numeric range, with the same syntax used to index shell
- variables, which must include the current word.
- .PD
- .RE
- .PP
- \fIlist\fR, the list of possible completions, may be one of the following:
- .PP
- .PD 0
- .RS +4
- .TP 8
- .B a
- Aliases
- .TP 8
- .B b
- Bindings (editor commands)
- .TP 8
- .B c
- Commands (builtin or external commands)
- .TP 8
- .B C
- External commands which begin with the supplied path prefix
- .TP 8
- .B d
- Directories
- .TP 8
- .B D
- Directories which begin with the supplied path prefix
- .TP 8
- .B e
- Environment variables
- .TP 8
- .B f
- Filenames
- .TP 8
- .B F
- Filenames which begin with the supplied path prefix
- .TP 8
- .B g
- Groupnames
- .TP 8
- .B j
- Jobs
- .TP 8
- .B l
- Limits
- .TP 8
- .B n
- Nothing
- .TP 8
- .B s
- Shell variables
- .TP 8
- .B S
- Signals
- .TP 8
- .B t
- Plain (``text'') files
- .TP 8
- .B T
- Plain (``text'') files which begin with the supplied path prefix
- .TP 8
- .B v
- Any variables
- .TP 8
- .B u
- Usernames
- .TP 8
- .B x
- Like \fBn\fR, but prints \fIselect\fR when \fIlist-choices\fR is used.
- .TP 8
- .B X
- Completions
- .TP 8
- $\fIvar\fR
- Words from the variable \fIvar\fR
- .TP 8
- (...)
- Words from the given list
- .TP 8
- `...`
- Words from the output of command
- .PD
- .RE
- .PP
- \fIselect\fR is an optional glob-pattern.
- If given, words from only \fIlist\fR that match \fIselect\fR are considered
- and the \fBfignore\fR shell variable is ignored.
- The last three types of completion may not have a \fIselect\fR
- pattern, and \fBx\fR uses \fIselect\fR as an explanatory message when
- the \fIlist-choices\fR editor command is used.
- .PP
- \fIsuffix\fR is a single character to be appended to a successful
- completion. If null, no character is appended. If omitted (in which
- case the fourth delimiter can also be omitted), a slash is appended to
- directories and a space to other words.
- .PP
- \fIcommand\fR invoked from `...` version has additional environment
- variable set, the variable name is \%\fBCOMMAND_LINE\fR\% and
- contains (as its name indicates) contents of the current (already
- typed in) command line. One can examine and use contents of the
- \%\fBCOMMAND_LINE\fR\% variable in her custom script to build more
- sophisticated completions (see completion for svn(1) included in
- this package).
- .PP
- Now for some examples. Some commands take only directories as arguments,
- so there's no point completing plain files.
- .IP "" 4
- > complete cd 'p/1/d/'
- .PP
- completes only the first word following `cd' (`p/1') with a directory.
- \fBp\fR-type completion can also be used to narrow down command completion:
- .IP "" 4
- > co[^D]
- .br
- complete compress
- .br
- > complete \-co* 'p/0/(compress)/'
- .br
- > co[^D]
- .br
- > compress
- .PP
- This completion completes commands (words in position 0, `p/0')
- which begin with `co' (thus matching `co*') to `compress' (the only
- word in the list).
- The leading `\-' indicates that this completion is to be used with only
- ambiguous commands.
- .IP "" 4
- > complete find 'n/\-user/u/'
- .PP
- is an example of \fBn\fR-type completion. Any word following `find' and
- immediately following `\-user' is completed from the list of users.
- .IP "" 4
- > complete cc 'c/\-I/d/'
- .PP
- demonstrates \fBc\fR-type completion. Any word following `cc' and beginning
- with `\-I' is completed as a directory. `\-I' is not taken as part of the
- directory because we used lowercase \fBc\fR.
- .PP
- Different \fIlist\fRs are useful with different commands.
- .IP "" 4
- > complete alias 'p/1/a/'
- .br
- > complete man 'p/*/c/'
- .br
- > complete set 'p/1/s/'
- .br
- > complete true 'p/1/x:Truth has no options./'
- .PP
- These complete words following `alias' with aliases, `man' with commands,
- and `set' with shell variables.
- `true' doesn't have any options, so \fBx\fR does nothing when completion
- is attempted and prints `Truth has no options.' when completion choices are listed.
- .PP
- Note that the \fIman\fR example, and several other examples below, could
- just as well have used 'c/*' or 'n/*' as 'p/*'.
- .PP
- Words can be completed from a variable evaluated at completion time,
- .IP "" 4
- > complete ftp 'p/1/$hostnames/'
- .br
- > set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu)
- .br
- > ftp [^D]
- .br
- rtfm.mit.edu tesla.ee.cornell.edu
- .br
- > ftp [^C]
- .br
- > set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net)
- .br
- > ftp [^D]
- .br
- rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net
- .PP
- or from a command run at completion time:
- .IP "" 4
- > complete kill 'p/*/`ps | awk \\{print\\ \\$1\\}`/'
- .br
- > kill \-9 [^D]
- .br
- 23113 23377 23380 23406 23429 23529 23530 PID
- .PP
- Note that the \fIcomplete\fR command does not itself quote its arguments,
- so the braces, space and `$' in `{print $1}' must be quoted explicitly.
- .PP
- One command can have multiple completions:
- .IP "" 4
- > complete dbx 'p/2/(core)/' 'p/*/c/'
- .PP
- completes the second argument to `dbx' with the word `core' and all other
- arguments with commands. Note that the positional completion is specified
- before the next-word completion.
- Because completions are evaluated from left to right, if
- the next-word completion were specified first it would always match
- and the positional completion would never be executed. This is a
- common mistake when defining a completion.
- .PP
- The \fIselect\fR pattern is useful when a command takes files with only
- particular forms as arguments. For example,
- .IP "" 4
- > complete cc 'p/*/f:*.[cao]/'
- .PP
- completes `cc' arguments to files ending in only `.c', `.a', or `.o'.
- \fIselect\fR can also exclude files, using negation of a glob-pattern as
- described under \fBFilename substitution\fR. One might use
- .IP "" 4
- > complete rm 'p/*/f:^*.{c,h,cc,C,tex,1,man,l,y}/'
- .PP
- to exclude precious source code from `rm' completion. Of course, one
- could still type excluded names manually or override the completion
- mechanism using the \fIcomplete-word-raw\fR or \fIlist-choices-raw\fR
- editor commands (q.v.).
- .PP
- The `C', `D', `F' and `T' \fIlist\fRs are like `c', `d', `f' and `t'
- respectively, but they use the \fIselect\fR argument in a different way: to
- restrict completion to files beginning with a particular path prefix. For
- example, the Elm mail program uses `=' as an abbreviation for one's mail
- directory. One might use
- .IP "" 4
- > complete elm c@=@F:$HOME/Mail/@
- .PP
- to complete `elm \-f =' as if it were `elm \-f ~/Mail/'. Note that we used `@'
- instead of `/' to avoid confusion with the \fIselect\fR argument, and we used
- `$HOME' instead of `~' because home directory substitution works at only the
- beginning of a word.
- .PP
- \fIsuffix\fR is used to add a nonstandard suffix
- (not space or `/' for directories) to completed words.
- .IP "" 4
- > complete finger 'c/*@/$hostnames/' 'p/1/u/@'
- .PP
- completes arguments to `finger' from the list of users, appends an `@',
- and then completes after the `@' from the `hostnames' variable. Note
- again the order in which the completions are specified.
- .PP
- Finally, here's a complex example for inspiration:
- .IP "" 4
- > complete find \\
- .br
- \&'n/\-name/f/' 'n/\-newer/f/' 'n/\-{,n}cpio/f/' \e
- .br
- \&\'n/\-exec/c/' 'n/\-ok/c/' 'n/\-user/u/' \e
- .br
- \&'n/\-group/g/' 'n/\-fstype/(nfs 4.2)/' \e
- .br
- \&'n/\-type/(b c d f l p s)/' \e
- .br
- \'c/\-/(name newer cpio ncpio exec ok user \e
- .br
- group fstype type atime ctime depth inum \e
- .br
- ls mtime nogroup nouser perm print prune \e
- .br
- size xdev)/' \e
- .br
- \&'p/*/d/'
- .PP
- This completes words following `\-name', `\-newer', `\-cpio' or `ncpio'
- (note the pattern which matches both) to files,
- words following `\-exec' or `\-ok' to commands, words following `user'
- and `group' to users and groups respectively
- and words following `\-fstype' or `\-type' to members of the
- given lists. It also completes the switches themselves from the given list
- (note the use of \fBc\fR-type completion)
- and completes anything not otherwise completed to a directory. Whew.
- .PP
- Remember that programmed completions are ignored if the word being completed
- is a tilde substitution (beginning with `~') or a variable (beginning with `$').
- \fIcomplete\fR is an experimental feature, and the syntax may change
- in future versions of the shell.
- See also the \fIuncomplete\fR builtin command.
- .RE
- .TP 8
- .B continue
- Continues execution of the nearest enclosing \fIwhile\fR or \fIforeach\fR.
- The rest of the commands on the current line are executed.
- .TP 8
- .B default:
- Labels the default case in a \fIswitch\fR statement.
- It should come after all \fIcase\fR labels.
- .PP
- .B dirs \fR[\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR]
- .br
- .B dirs \-S\fR|\fB\-L \fR[\fIfilename\fR] (+)
- .PD 0
- .TP 8
- .B dirs \-c \fR(+)
- The first form prints the directory stack. The top of the stack is at the
- left and the first directory in the stack is the current directory.
- With \fB\-l\fR, `~' or `~\fIname\fP' in the output is expanded explicitly
- to \fBhome\fR or the pathname of the home directory for user \fIname\fP. (+)
- With \fB\-n\fR, entries are wrapped before they reach the edge of the screen. (+)
- With \fB\-v\fR, entries are printed one per line, preceded by their stack positions. (+)
- If more than one of \fB\-n\fR or \fB\-v\fR is given, \fB\-v\fR takes precedence.
- \fB\-p\fR is accepted but does nothing.
- .PD
- .RS +8
- .PP
- With \fB\-S\fR, the second form saves the directory stack to \fIfilename\fR
- as a series of \fIcd\fR and \fIpushd\fR commands.
- With \fB\-L\fR, the shell sources \fIfilename\fR, which is presumably
- a directory stack file saved by the \fB\-S\fR option or the \fBsavedirs\fR
- mechanism.
- In either case, \fBdirsfile\fR is used if \fIfilename\fR is not given and
- \fI~/.cshdirs\fR is used if \fBdirsfile\fR is unset.
- .PP
- Note that login shells do the equivalent of `dirs \-L' on startup
- and, if \fBsavedirs\fR is set, `dirs \-S' before exiting.
- Because only \fI~/.tcshrc\fR is normally sourced before \fI~/.cshdirs\fR,
- \fBdirsfile\fR should be set in \fI~/.tcshrc\fR rather than \fI~/.login\fR.
- .PP
- The last form clears the directory stack.
- .RE
- .TP 8
- .B echo \fR[\fB\-n\fR] \fIword\fR ...
- Writes each \fIword\fR to the shell's standard
- output, separated by spaces and terminated with a newline.
- The \fBecho_style\fR shell variable may be set to emulate (or not) the flags and escape
- sequences of the BSD and/or System V versions of \fIecho\fR; see \fIecho\fR(1).
- .TP 8
- .B echotc \fR[\fB\-sv\fR] \fIarg\fR ... (+)
- Exercises the terminal capabilities (see \fItermcap\fR(5)) in \fIargs\fR.
- For example, 'echotc home' sends the cursor to the home position,
- \&'echotc cm 3 10' sends it to column 3 and row 10, and
- \&'echotc ts 0; echo "This is a test."; echotc fs' prints "This is a test."
- in the status line.
- .RS +8
- .PP
- If \fIarg\fR is 'baud', 'cols', 'lines', 'meta' or 'tabs', prints the
- value of that capability ("yes" or "no" indicating that the terminal does
- or does not have that capability). One might use this to make the output
- from a shell script less verbose on slow terminals, or limit command
- output to the number of lines on the screen:
- .IP "" 4
- > set history=`echotc lines`
- .br
- > @ history\-\-
- .PP
- Termcap strings may contain wildcards which will not echo correctly.
- One should use double quotes when setting a shell variable to a terminal
- capability string, as in the following example that places the date in
- the status line:
- .IP "" 4
- > set tosl="`echotc ts 0`"
- .br
- > set frsl="`echotc fs`"
- .br
- > echo \-n "$tosl";date; echo \-n "$frsl"
- .PP
- With \fB\-s\fR, nonexistent capabilities return the empty string rather
- than causing an error.
- With \fB\-v\fR, messages are verbose.
- .RE
- .PP
- .B else
- .br
- .B end
- .br
- .B endif
- .PD 0
- .TP 8
- .B endsw
- See the description of the \fIforeach\fR, \fIif\fR, \fIswitch\fR, and
- \fIwhile\fR statements below.
- .PD
- .TP 8
- .B eval \fIarg\fR ...
- Treats the arguments as input to the
- shell and executes the resulting command(s) in the context
- of the current shell. This is usually used to execute commands
- generated as the result of command or variable substitution,
- because parsing occurs before these substitutions.
- See \fItset\fR(1) for a sample use of \fIeval\fR.
- .TP 8
- .B exec \fIcommand\fR
- Executes the specified command in place of the current shell.
- .TP 8
- .B exit \fR[\fIexpr\fR]
- The shell exits either with the value of the specified \fIexpr\fR
- (an expression, as described under \fBExpressions\fR)
- or, without \fIexpr\fR, with the value 0.
- .TP 8
- .B fg \fR[\fB%\fIjob\fR ...]
- Brings the specified jobs (or, without arguments, the current job)
- into the foreground, continuing each if it is stopped.
- \fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
- under \fBJobs\fR.
- See also the \fIrun-fg-editor\fR editor command.
- .TP 8
- .B filetest \-\fIop file\fR ... (+)
- Applies \fIop\fR (which is a file inquiry operator as described under
- \fBFile inquiry operators\fR) to each \fIfile\fR and returns the results as a
- space-separated list.
- .PP
- .B foreach \fIname \fB(\fIwordlist\fB)
- .br
- \&...
- .PD 0
- .TP 8
- .B end
- Successively sets the variable \fIname\fR to each member of
- \fIwordlist\fR and executes the sequence of commands between this command
- and the matching \fIend\fR. (Both \fIforeach\fR and \fIend\fR
- must appear alone on separate lines.) The builtin command
- \fIcontinue\fR may be used to continue the loop prematurely and
- the builtin command \fIbreak\fR to terminate it prematurely.
- When this command is read from the terminal, the loop is read once
- prompting with `foreach? ' (or \fBprompt2\fR) before any statements in
- the loop are executed. If you make a mistake typing in a
- loop at the terminal you can rub it out.
- .PD
- .TP 8
- .B getspath \fR(+)
- Prints the system execution path. (TCF only)
- .TP 8
- .B getxvers \fR(+)
- Prints the experimental version prefix. (TCF only)
- .TP 8
- .B glob \fIwordlist
- Like \fIecho\fR, but the `-n' parameter is not recognized and words are
- delimited by null characters in the output. Useful for
- programs which wish to use the shell to filename expand a list of words.
- .TP 8
- .B goto \fIword
- \fIword\fR is filename and command-substituted to
- yield a string of the form `label'. The shell rewinds its
- input as much as possible, searches for a line of the
- form `label:', possibly preceded by blanks or tabs, and
- continues execution after that line.
- .TP 8
- .B hashstat
- Prints a statistics line indicating how effective the
- internal hash table has been at locating commands (and avoiding
- \fIexec\fR's). An \fIexec\fR is attempted for each component of the
- \fBpath\fR where the hash function indicates a possible hit, and
- in each component which does not begin with a `/'.
- .IP
- On machines without \fIvfork\fR(2), prints only the number and size of
- hash buckets.
- .PP
- .B history \fR[\fB\-hTr\fR] [\fIn\fR]
- .br
- .B history \-S\fR|\fB\-L|\fB\-M \fR[\fIfilename\fR] (+)
- .PD 0
- .TP 8
- .B history \-c \fR(+)
- The first form prints the history event list.
- If \fIn\fR is given only the \fIn\fR most recent events are printed or saved.
- With \fB\-h\fR, the history list is printed without leading numbers. If
- \fB-T\fR is specified, timestamps are printed also in comment form.
- (This can be used to
- produce files suitable for loading with 'history \-L' or 'source \-h'.)
- With \fB\-r\fR, the order of printing is most recent
- first rather than oldest first.
- .PD
- .RS +8
- .PP
- With \fB\-S\fR, the second form saves the history list to \fIfilename\fR.
- If the first word of the \fBsavehist\fR shell variable is set to a
- number, at most that many lines are saved. If the second word of
- \fBsavehist\fR 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. (+) Merging is intended for an environment like
- the X Window System
- with several shells in simultaneous use. Currently it succeeds
- only when the shells quit nicely one after another.
- .PP
- With \fB\-L\fR, the shell appends \fIfilename\fR, which is presumably a
- history list saved by the \fB\-S\fR option or the \fBsavehist\fR mechanism,
- to the history list.
- \fB\-M\fR is like \fB\-L\fR, but the contents of \fIfilename\fR are merged
- into the history list and sorted by timestamp.
- In either case, \fBhistfile\fR is used if \fIfilename\fR is not given and
- \fI~/.history\fR is used if \fBhistfile\fR is unset.
- `history \-L' is exactly like 'source \-h' except that it does not require a
- filename.
- .PP
- Note that login shells do the equivalent of `history \-L' on startup
- and, if \fBsavehist\fR is set, `history \-S' before exiting.
- Because only \fI~/.tcshrc\fR is normally sourced before \fI~/.history\fR,
- \fBhistfile\fR should be set in \fI~/.tcshrc\fR rather than \fI~/.login\fR.
- .PP
- If \fBhistlit\fR is set, the first and second forms print and save the literal
- (unexpanded) form of the history list.
- .PP
- The last form clears the history list.
- .RE
- .TP 8
- .B hup \fR[\fIcommand\fR] \fR(+)
- With \fIcommand\fR, runs \fIcommand\fR such that it will exit on a hangup
- signal and arranges for the shell to send it a hangup signal when the shell
- exits.
- Note that commands may set their own response to hangups, overriding \fIhup\fR.
- Without an argument, causes the non-interactive shell only to
- exit on a hangup for the remainder of the script.
- See also \fBSignal handling\fR and the \fInohup\fR builtin command.
- .TP 8
- .B if (\fIexpr\fB) \fIcommand
- If \fIexpr\fR (an expression, as described under \fBExpressions\fR)
- evaluates true, then \fIcommand\fR is executed.
- Variable substitution on \fIcommand\fR happens early, at the same time it
- does for the rest of the \fIif\fR command.
- \fIcommand\fR must be a simple command, not an alias, a pipeline, a command list
- or a parenthesized command list, but it may have arguments.
- Input/output redirection occurs even if \fIexpr\fR is
- false and \fIcommand\fR is thus \fInot\fR executed; this is a bug.
- .PP
- .B if (\fIexpr\fB) then
- .br
- \&...
- .br
- .B else if (\fIexpr2\fB) then
- .br
- \&...
- .br
- .B else
- .br
- \&...
- .PD 0
- .TP 8
- .B endif
- If the specified \fIexpr\fR is true then the commands to the
- first \fIelse\fR are executed; otherwise if \fIexpr2\fR is true then
- the commands to the second \fIelse\fR are executed, etc. Any
- number of \fIelse-if\fR pairs are possible; only one \fIendif\fR is
- needed. The \fIelse\fR part is likewise optional. (The words
- \fIelse\fR and \fIendif\fR must appear at the beginning of input lines;
- the \fIif\fR must appear alone on its input line or after an
- \fIelse\fR.)
- .PD
- .TP 8
- .B inlib \fIshared-library\fR ... (+)
- Adds each \fIshared-library\fR to the current environment. There is no way
- to remove a shared library. (Domain/OS only)
- .TP 8
- .B jobs \fR[\fB\-l\fR]
- Lists the active jobs. With \fB\-l\fR, lists process
- IDs in addition to the normal information. On TCF systems, prints
- the site on which each job is executing.
- .PP
- .PD 0
- .TP 8
- .B kill \fR[\fB\-s \fIsignal\fR] \fB%\fIjob\fR|\fIpid\fR ...
- .PD 0
- .TP 8
- .B kill \-l
- The first and second forms sends the specified \fIsignal\fR (or, if none
- is given, the TERM (terminate) signal) to the specified jobs or processes.
- \fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
- under \fBJobs\fR.
- Signals are either given by number or by name (as given in
- \fI/usr/include/signal.h\fR, stripped of the prefix `SIG').
- There is no default \fIjob\fR; saying just `kill' does not send a signal
- to the current job. If the signal being sent is TERM (terminate)
- or HUP (hangup), then the job or process is sent a
- CONT (continue) signal as well.
- The third form lists the signal names.
- .PD
- .TP 8
- .B limit \fR[\fB\-h\fR] [\fIresource\fR [\fImaximum-use\fR]]
- Limits the consumption by the current process and each
- process it creates to not individually exceed \fImaximum-use\fR on
- the specified \fIresource\fR. If no \fImaximum-use\fR is given, then
- the current limit is printed; if no \fIresource\fR is given, then
- all limitations are given. If the \fB\-h\fR flag is given, the
- hard limits are used instead of the current limits. The
- hard limits impose a ceiling on the values of the current
- limits. Only the super-user may raise the hard limits, but
- a user may lower or raise the current limits within the legal range.
- .RS +8
- .PP
- Controllable resources currently include (if supported by the OS):
- .TP
- \fIcputime\fR
- the maximum number of cpu-seconds to be used by each process
- .TP
- \fIfilesize\fR
- the largest single file which can be created
- .TP
- \fIdatasize\fR
- the maximum growth of the data+stack region via sbrk(2) beyond
- the end of the program text
- .TP
- \fIstacksize\fR
- the maximum size of the automatically-extended stack region
- .TP
- \fIcoredumpsize\fR
- the size of the largest core dump that will be created
- .TP
- \fImemoryuse\fR
- the maximum amount of physical memory a process
- may have allocated to it at a given time
- .TP
- \fIvmemoryuse\fR
- the maximum amount of virtual memory a process
- may have allocated to it at a given time (address space)
- .TP
- \fIvmemoryuse\fR
- the maximum amount of virtual memory a process
- may have allocated to it at a given time
- .TP
- \fIheapsize\fR
- the maximum amount of memory a process
- may allocate per \fIbrk()\fR system call
- .TP
- \fIdescriptors\fR or \fIopenfiles\fR
- the maximum number of open files for this process
- .TP
- \fIconcurrency\fR
- the maximum number of threads for this process
- .TP
- \fImemorylocked\fR
- the maximum size which a process may lock into memory using mlock(2)
- .TP
- \fImaxproc\fR
- the maximum number of simultaneous processes for this user id
- .TP
- \fIsbsize\fR
- the maximum size of socket buffer usage for this user
- .TP
- \fIswapsize\fR
- the maximum amount of swap space reserved or used for this user
- .TP
- \fImaxlocks\fR
- the maximum number of locks for this user
- .TP
- \fImaxsignal\fR
- the maximum number of pending signals for this user
- .TP
- \fImaxmessage\fR
- the maximum number of bytes in POSIX mqueues for this user
- .TP
- \fImaxnice\fR
- the maximum nice priority the user is allowed to raise mapped from [19...-20]
- to [0...39] for this user
- .TP
- \fImaxrtprio\fR
- the maximum realtime priority for this user
- \fImaxrttime\fR
- the timeout for RT tasks in microseconds for this user.
- .PP
- \fImaximum-use\fR may be given as a (floating point or
- integer) number followed by a scale factor. For all limits
- other than \fIcputime\fR the default scale is `k' or `kilobytes'
- (1024 bytes); a scale factor of `m' or `megabytes' or `g' or `gigabytes'
- may also be used. For \fIcputime\fR the default scaling is `seconds',
- while `m' for minutes or `h' for hours, or a time of the
- form `mm:ss' giving minutes and seconds may be used.
- .PP
- If \fImaximum-use\fR is `unlimited',
- then the limitation on the specified \fIresource\fR
- is removed (this is equivalent to the \fIunlimit\fR builtin command).
- .PP
- For both \fIresource\fR names and scale factors, unambiguous
- prefixes of the names suffice.
- .RE
- .TP 8
- .B log \fR(+)
- Prints the \fBwatch\fR shell variable and reports on each user indicated
- in \fBwatch\fR who is logged in, regardless of when they last logged in.
- See also \fIwatchlog\fR.
- .TP 8
- .B login
- Terminates a login shell, replacing it with an instance of
- \fI/bin/login\fR. This is one way to log off, included for
- compatibility with \fIsh\fR(1).
- .TP 8
- .B logout
- Terminates a login shell. Especially useful if \fBignoreeof\fR is set.
- .TP 8
- .B ls\-F \fR[\-\fIswitch\fR ...] [\fIfile\fR ...] (+)
- Lists files like `ls \-F', but much faster. It identifies each type of
- special file in the listing with a special character:
- .PP
- .RS +8
- .PD 0
- .TP 4
- /
- Directory
- .TP 4
- *
- Executable
- .TP 4
- #
- Block device
- .TP 4
- %
- Character device
- .TP 4
- |
- Named pipe (systems with named pipes only)
- .TP 4
- =
- Socket (systems with sockets only)
- .TP 4
- @
- Symbolic link (systems with symbolic links only)
- .TP 4
- +
- Hidden directory (AIX only) or context dependent (HP/UX only)
- .TP 4
- :
- Network special (HP/UX only)
- .PD
- .PP
- If the \fBlistlinks\fR shell variable is set, symbolic links are identified
- in more detail (on only systems that have them, of course):
- .PP
- .PD 0
- .TP 4
- @
- Symbolic link to a non-directory
- .TP 4
- >
- Symbolic link to a directory
- .TP 4
- &
- Symbolic link to nowhere
- .PD
- .PP
- \fBlistlinks\fR also slows down \fIls\-F\fR and causes partitions holding
- files pointed to by symbolic links to be mounted.
- .PP
- If the \fBlistflags\fR shell variable is set to `x', `a' or `A', or any
- combination thereof (e.g., `xA'), they are used as flags to \fIls\-F\fR,
- making it act like `ls \-xF', `ls \-Fa', `ls \-FA' or a combination
- (e.g., `ls \-FxA').
- On machines where `ls \-C' is not the default, \fIls\-F\fR acts like `ls \-CF',
- unless \fBlistflags\fR contains an `x', in which case it acts like `ls \-xF'.
- \fIls\-F\fR passes its arguments to \fIls\fR(1) if it is given any switches,
- so `alias ls ls\-F' generally does the right thing.
- .PP
- The \fBls\-F\fR builtin can list files using different colors depending on the
- filetype or extension. See the \fBcolor\fR shell variable and the
- \fBLS_COLORS\fR environment variable.
- .RE
- .PP
- .B migrate \fR[\fB\-\fIsite\fR] \fIpid\fR|\fB%\fIjobid\fR ... (+)
- .PD 0
- .TP 8
- .B migrate \-\fIsite\fR (+)
- The first form migrates the process or job to the site specified or the
- default site determined by the system path.
- The second form is equivalent to `migrate \-\fIsite\fR $$': it migrates the
- current process to the specified site. Migrating the shell
- itself can cause unexpected behavior, because the shell
- does not like to lose its tty. (TCF only)
- .PD
- .TP 8
- .B newgrp \fR[\fB\-\fR] \fI[group]\fR (+)
- Equivalent to `exec newgrp'; see \fInewgrp\fR(1).
- Available only if the shell was so compiled;
- see the \fBversion\fR shell variable.
- .TP 8
- .B nice \fR[\fB+\fInumber\fR] [\fIcommand\fR]
- Sets the scheduling priority for the shell to \fInumber\fR, or, without
- \fInumber\fR, to 4. With \fIcommand\fR, runs \fIcommand\fR at the appropriate
- priority.
- The greater the \fInumber\fR, the less cpu
- the process gets. The super-user may specify negative
- priority by using `nice \-number ...'. Command is always
- executed in a sub-shell, and the restrictions placed on
- commands in simple \fIif\fR statements apply.
- .TP 8
- .B nohup \fR[\fIcommand\fR]
- With \fIcommand\fR, runs \fIcommand\fR such that it will ignore hangup signals.
- Note that commands may set their own response to hangups, overriding \fInohup\fR.
- Without an argument, causes the non-interactive shell only to
- ignore hangups for the remainder of the script.
- See also \fBSignal handling\fR and the \fIhup\fR builtin command.
- .TP 8
- .B notify \fR[\fB%\fIjob\fR ...]
- Causes the shell to notify the user asynchronously when the status of any
- of the specified jobs (or, without %\fIjob\fR, the current job) changes,
- instead of waiting until the next prompt as is usual.
- \fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
- under \fBJobs\fR.
- See also the \fBnotify\fR shell variable.
- .TP 8
- .B onintr \fR[\fB\-\fR|\fIlabel\fR]
- Controls the action of the shell on interrupts. Without arguments,
- restores the default action of the shell on interrupts,
- which is to terminate shell scripts or to return to the
- terminal command input level.
- With `\-', causes all interrupts to be ignored.
- With \fIlabel\fR, causes the shell to execute a `goto \fIlabel\fR'
- when an interrupt is received or a child process terminates because it was
- interrupted.
- .IP "" 8
- \fIonintr\fR is ignored if the shell is running detached and in system
- startup files (see \fBFILES\fR), where interrupts are disabled anyway.
- .TP 8
- .B popd \fR[\fB\-p\fR] [\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR] \fR[\fB+\fIn\fR]
- Without arguments, pops the directory stack and returns to the new top directory.
- With a number `+\fIn\fR', discards the \fIn\fR'th entry in the stack.
- .IP "" 8
- Finally, all forms of \fIpopd\fR print the final directory stack,
- just like \fIdirs\fR. The \fBpushdsilent\fR shell variable can be set to
- prevent this and the \fB\-p\fR flag can be given to override \fBpushdsilent\fR.
- The \fB\-l\fR, \fB\-n\fR and \fB\-v\fR flags have the same effect on \fIpopd\fR
- as on \fIdirs\fR. (+)
- .TP 8
- .B printenv \fR[\fIname\fR] (+)
- Prints the names and values of all environment variables or,
- with \fIname\fR, the value of the environment variable \fIname\fR.
- .TP 8
- .B pushd \fR[\fB\-p\fR] [\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR] [\fIname\fR|\fB+\fIn\fR]
- Without arguments, exchanges the top two elements of the directory stack.
- If \fBpushdtohome\fR is set, \fIpushd\fR without arguments does `pushd ~',
- like \fIcd\fR. (+)
- With \fIname\fR, pushes the current working directory onto the directory
- stack and changes to \fIname\fR.
- If \fIname\fR is `\-' it is interpreted as the previous working directory
- (see \fBFilename substitution\fR). (+)
- If \fBdunique\fR is set, \fIpushd\fR removes any instances of \fIname\fR
- from the stack before pushing it onto the stack. (+)
- With a number `+\fIn\fR', rotates the \fIn\fRth element of the
- directory stack around to be the top element and changes to it.
- If \fBdextract\fR is set, however, `pushd +\fIn\fR' extracts the \fIn\fRth
- directory, pushes it onto the top of the stack and changes to it. (+)
- .IP "" 8
- Finally, all forms of \fIpushd\fR print the final directory stack,
- just like \fIdirs\fR. The \fBpushdsilent\fR shell variable can be set to
- prevent this and the \fB\-p\fR flag can be given to override \fBpushdsilent\fR.
- The \fB\-l\fR, \fB\-n\fR and \fB\-v\fR flags have the same effect on \fIpushd\fR
- as on \fIdirs\fR. (+)
- .TP 8
- .B rehash
- Causes the internal hash table of the contents of the
- directories in the \fBpath\fR variable to be recomputed. This is
- needed if the \fBautorehash\fR shell variable is not set and new
- commands are added to directories in \fBpath\fR while you are logged
- in. With \fBautorehash\fR, a new command will be found
- automatically, except in the special case where another command of
- the same name which is located in a different directory already
- exists in the hash table. Also flushes the cache of home directories
- built by tilde expansion.
- .TP 8
- .B repeat \fIcount command
- The specified \fIcommand\fR,
- which is subject to the same restrictions as the \fIcommand\fR
- in the one line \fIif\fR statement above, is executed \fIcount\fR times.
- I/O redirections occur exactly once, even if \fIcount\fR is 0.
- .TP 8
- .B rootnode //\fInodename \fR(+)
- Changes the rootnode to //\fInodename\fR, so that `/' will be interpreted
- as `//\fInodename\fR'. (Domain/OS only)
- .PP
- .B sched \fR(+)
- .br
- .B sched \fR[\fB+\fR]\fIhh:mm command\fR \fR(+)
- .PD 0
- .TP 8
- .B sched \-\fIn\fR (+)
- The first form prints the scheduled-event list.
- The \fBsched\fR shell variable may be set to define the format in which
- the scheduled-event list is printed.
- The second form adds \fIcommand\fR to the scheduled-event list.
- For example,
- .PD
- .RS +8
- .IP "" 4
- > sched 11:00 echo It\\'s eleven o\\'clock.
- .PP
- causes the shell to echo `It's eleven o'clock.' at 11 AM.
- The time may be in 12-hour AM/PM format
- .IP "" 4
- > sched 5pm set prompt='[%h] It\\'s after 5; go home: >'
- .PP
- or may be relative to the current time:
- .IP "" 4
- > sched +2:15 /usr/lib/uucp/uucico \-r1 \-sother
- .PP
- A relative time specification may not use AM/PM format.
- The third form removes item \fIn\fR from the event list:
- .IP "" 4
- > sched
- .br
- 1 Wed Apr 4 15:42 /usr/lib/uucp/uucico \-r1 \-sother
- .br
- 2 Wed Apr 4 17:00 set prompt=[%h] It's after 5; go home: >
- .br
- > sched \-2
- .br
- > sched
- .br
- 1 Wed Apr 4 15:42 /usr/lib/uucp/uucico \-r1 \-sother
- .PP
- A command in the scheduled-event list is executed just before the first
- prompt is printed after the time when the command is scheduled.
- It is possible to miss the exact time when the command is to be run, but
- an overdue command will execute at the next prompt.
- A command which comes due while the shell
- is waiting for user input is executed immediately.
- However, normal operation of an already-running command will not
- be interrupted so that a scheduled-event list element may be run.
- .PP
- This mechanism is similar to, but not the same as, the \fIat\fR(1)
- command on some Unix systems.
- Its major disadvantage is that it may not run a command at exactly the
- specified time.
- Its major advantage is that because \fIsched\fR runs directly from
- the shell, it has access to shell variables and other structures.
- This provides a mechanism for changing one's working environment
- based on the time of day.
- .RE
- .PP
- .B set
- .br
- .B set \fIname\fR ...
- .br
- .B set \fIname\fR\fB=\fIword\fR ...
- .br
- .B set [\-r] [\-f|\-l] \fIname\fR\fB=(\fIwordlist\fB)\fR ... (+)
- .br
- .B set \fIname[index]\fR\fB=\fIword\fR ...
- .br
- .B set \-r \fR(+)
- .br
- .B set \-r \fIname\fR ... (+)
- .PD 0
- .TP 8
- .B set \-r \fIname\fR\fB=\fIword\fR ... (+)
- The first form of the command prints the value of all shell variables.
- Variables which contain more than a single word print as a
- parenthesized word list.
- The second form sets \fIname\fR to the null string.
- The third form sets \fIname\fR to the single \fIword\fR.
- The fourth form sets \fIname\fR to the list of words in
- \fIwordlist\fR. In all cases the value is command and filename expanded.
- If \fB\-r\fR is specified, the value is set read-only. If \fB\-f\fR or
- \fB\-l\fR are specified, set only unique words keeping their order.
- \fB\-f\fR prefers the first occurrence of a word, and \fB\-l\fR the last.
- The fifth form sets the \fIindex\fR'th component of \fIname\fR to \fIword\fR;
- this component must already exist.
- The sixth form lists only the names of all shell variables that are read-only.
- The seventh form makes \fIname\fR read-only, whether or not it has a value.
- The eighth form is the same as the third form, but
- make \fIname\fR read-only at the same time.
- .PD
- .IP "" 8
- These arguments can be repeated to set and/or make read-only multiple variables
- in a single set command. Note, however, that variable expansion
- happens for all arguments before any setting occurs. Note also that `=' can
- be adjacent to both \fIname\fR and \fIword\fR or separated from both by
- whitespace, but cannot be adjacent to only one or the other.
- See also the \fIunset\fR builtin command.
- .TP 8
- .B setenv \fR[\fIname \fR[\fIvalue\fR]]
- Without arguments, prints the names and values of all environment variables.
- Given \fIname\fR, sets the environment variable \fIname\fR to \fIvalue\fR
- or, without \fIvalue\fR, to the null string.
- .TP 8
- .B setpath \fIpath \fR(+)
- Equivalent to \fIsetpath\fR(1). (Mach only)
- .TP 8
- .B setspath\fR LOCAL|\fIsite\fR|\fIcpu\fR ... (+)
- Sets the system execution path. (TCF only)
- .TP 8
- .B settc \fIcap value \fR(+)
- Tells the shell to believe that the terminal capability \fIcap\fR
- (as defined in \fItermcap\fR(5)) has the value \fIvalue\fR.
- No sanity checking is done.
- Concept terminal users may have to `settc xn no' to get proper
- wrapping at the rightmost column.
- .TP 8
- .B setty \fR[\fB\-d\fR|\fB\-q\fR|\fB\-x\fR] [\fB\-a\fR] [[\fB+\fR|\fB\-\fR]\fImode\fR] (+)
- Controls which tty modes (see \fBTerminal management\fR)
- the shell does not allow to change.
- \fB\-d\fR, \fB\-q\fR or \fB\-x\fR tells \fIsetty\fR to act
- on the `edit', `quote' or `execute' set of tty modes respectively; without
- \fB\-d\fR, \fB\-q\fR or \fB\-x\fR, `execute' is used.
- .IP "" 8
- Without other arguments, \fIsetty\fR lists the modes in the chosen set
- which are fixed on (`+mode') or off (`\-mode').
- The available modes, and thus the display, vary from system to system.
- With \fB\-a\fR, lists all tty modes in the chosen set
- whether or not they are fixed.
- With \fB+\fImode\fR, \fB\-\fImode\fR or \fImode\fR, fixes \fImode\fR on or off
- or removes control from \fImode\fR in the chosen set.
- For example, `setty +echok echoe' fixes `echok' mode on and allows commands
- to turn `echoe' mode on or off, both when the shell is executing commands.
- .TP 8
- .B setxvers\fR [\fIstring\fR] (+)
- Set the experimental version prefix to \fIstring\fR, or removes it
- if \fIstring\fR is omitted. (TCF only)
- .TP 8
- .B shift \fR[\fIvariable\fR]
- Without arguments, discards \fBargv\fR[1] and shifts the members of
- \fBargv\fR to the left. It is an error for \fBargv\fR not to be set or to have
- less than one word as value. With \fIvariable\fR, performs the
- same function on \fIvariable\fR.
- .TP 8
- .B source \fR[\fB\-h\fR] \fIname\fR [\fIargs\fR ...]
- The shell reads and executes commands from \fIname\fR.
- The commands are not placed on the history list.
- If any \fIargs\fR are given, they are placed in \fBargv\fR. (+)
- \fIsource\fR commands may be nested;
- if they are nested too deeply the shell may run out of file descriptors.
- An error in a \fIsource\fR at any level terminates all nested
- \fIsource\fR commands.
- With \fB\-h\fR, commands are placed on the history list instead of being
- executed, much like `history \-L'.
- .TP 8
- .B stop \fB%\fIjob\fR|\fIpid\fR ...
- Stops the specified jobs or processes which are executing in the background.
- \fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
- under \fBJobs\fR.
- There is no default \fIjob\fR; saying just `stop' does not stop
- the current job.
- .TP 8
- .B suspend
- Causes the shell to stop in its tracks, much as if it had
- been sent a stop signal with \fB^Z\fR. This is most often used to
- stop shells started by \fIsu\fR(1).
- .PP
- .B switch (\fIstring\fB)
- .br
- .B case \fIstr1\fB:
- .PD 0
- .IP "" 4
- \&...
- .br
- .B breaksw
- .PP
- \&...
- .PP
- .B default:
- .IP "" 4
- \&...
- .br
- .B breaksw
- .TP 8
- .B endsw
- Each case label is successively matched, against the
- specified \fIstring\fR which is first command and filename expanded.
- The file metacharacters `*', `?' and `[...]' may be used
- in the case labels, which are variable expanded. If none
- of the labels match before a `default' label is found, then
- the execution begins after the default label. Each case
- label and the default label must appear at the beginning of
- a line. The command \fIbreaksw\fR causes execution to continue
- after the \fIendsw\fR. Otherwise control may fall through case
- labels and default labels as in C. If no label matches and
- there is no default, execution continues after the \fIendsw\fR.
- .PD
- .TP 8
- .B telltc \fR(+)
- Lists the values of all terminal capabilities (see \fItermcap\fR(5)).
- .TP 8
- .B termname \fR[\fIterminal type\fR] \fR(+)
- Tests if \fIterminal type\fR (or the current value of \fBTERM\fR if no
- \fIterminal type\fR is given) has an entry in the hosts termcap(5) or
- terminfo(5) database. Prints the terminal type to stdout and returns 0
- if an entry is present otherwise returns 1.
- .TP 8
- .B time \fR[\fIcommand\fR]
- Executes \fIcommand\fR (which must be a simple command, not an alias,
- a pipeline, a command list or a parenthesized command list)
- and prints a time summary as described under the \fBtime\fR variable.
- If necessary, an extra shell is created to print the time statistic when
- the command completes.
- Without \fIcommand\fR, prints a time summary for the current shell and its
- children.
- .TP 8
- .B umask \fR[\fIvalue\fR]
- Sets the file creation mask to \fIvalue\fR, which is given in octal.
- Common values for the mask are
- 002, giving all access to the group and read and execute access to others, and
- 022, giving read and execute access to the group and others.
- Without \fIvalue\fR, prints the current file creation mask.
- .TP 8
- .B unalias \fIpattern\fR
- .br
- Removes all aliases whose names match \fIpattern\fR.
- `unalias *' thus removes all aliases.
- It is not an error for nothing to be \fIunalias\fRed.
- .TP 8
- .B uncomplete \fIpattern\fR (+)
- Removes all completions whose names match \fIpattern\fR.
- `uncomplete *' thus removes all completions.
- It is not an error for nothing to be \fIuncomplete\fRd.
- .TP 8
- .B unhash
- Disables use of the internal hash table to speed location of
- executed programs.
- .TP 8
- .B universe \fIuniverse\fR (+)
- Sets the universe to \fIuniverse\fR. (Masscomp/RTU only)
- .TP 8
- .B unlimit \fR[\fB\-hf\fR] [\fIresource\fR]
- Removes the limitation on \fIresource\fR or, if no \fIresource\fR is
- specified, all \fIresource\fR limitations.
- With \fB\-h\fR, the corresponding hard limits are removed.
- Only the super-user may do this.
- Note that \fBunlimit\fR may not exit successful, since most systems
- do not allow \fIdescriptors\fR to be unlimited.
- With \fB\-f\fR errors are ignored.
- .TP 8
- .B unset \fIpattern
- Removes all variables whose names match \fIpattern\fR, unless they are read-only.
- `unset *' thus removes all variables unless they are read-only;
- this is a bad idea.
- It is not an error for nothing to be \fIunset\fR.
- .TP 8
- .B unsetenv \fIpattern
- Removes all environment variables whose names match \fIpattern\fR.
- `unsetenv *' thus removes all environment variables;
- this is a bad idea.
- It is not an error for nothing to be \fIunsetenv\fRed.
- .TP 8
- .B ver \fR[\fIsystype\fR [\fIcommand\fR]] (+)
- Without arguments, prints \fBSYSTYPE\fR. With \fIsystype\fR, sets \fBSYSTYPE\fR
- to \fIsystype\fR. With \fIsystype\fR and \fIcommand\fR, executes \fIcommand\fR
- under \fIsystype\fR. \fIsystype\fR may be `bsd4.3' or `sys5.3'.
- (Domain/OS only)
- .TP 8
- .B wait
- The shell waits for all background jobs. If the shell is interactive, an
- interrupt will disrupt the wait and cause the shell to print the names and job
- numbers of all outstanding jobs.
- .TP 8
- .B warp \fIuniverse\fR (+)
- Sets the universe to \fIuniverse\fR. (Convex/OS only)
- .TP 8
- .B watchlog \fR(+)
- An alternate name for the \fIlog\fR builtin command (q.v.).
- Available only if the shell was so compiled;
- see the \fBversion\fR shell variable.
- .TP 8
- .B where \fIcommand\fR (+)
- Reports all known instances of \fIcommand\fR, including aliases, builtins and
- executables in \fBpath\fR.
- .TP 8
- .B which\fR \fIcommand\fR (+)
- Displays the command that will be executed by the shell after substitutions,
- \fBpath\fR searching, etc.
- The builtin command is just like \fIwhich\fR(1), but it correctly reports
- \fItcsh\fR aliases and builtins and is 10 to 100 times faster.
- See also the \fIwhich-command\fR editor command.
- .PP
- .B while (\fIexpr\fB)\fR
- .br
- \&...
- .PD 0
- .TP 8
- .B end
- Executes the commands between the \fIwhile\fR and the matching \fIend\fR
- while \fIexpr\fR (an expression, as described under \fBExpressions\fR)
- evaluates non-zero.
- \fIwhile\fR and \fIend\fR must appear alone on their input lines.
- \fIbreak\fR and \fIcontinue\fR may be used to terminate or continue the
- loop prematurely.
- If the input is a terminal, the user is prompted the first time
- through the loop as with \fIforeach\fR.
- .PD
- .SS "Special aliases (+)"
- If set, each of these aliases executes automatically at the indicated time.
- They are all initially undefined.
- .TP 8
- .B beepcmd
- Runs when the shell wants to ring the terminal bell.
- .TP 8
- .B cwdcmd
- Runs after every change of working directory. For example, if the user is
- working on an X window system using \fIxterm\fR(1) and a re-parenting window
- manager that supports title bars such as \fItwm\fR(1) and does
- .RS +8
- .IP "" 4
- > alias cwdcmd 'echo \-n "^[]2;${HOST}:$cwd ^G"'
- .PP
- then the shell will change the title of the running \fIxterm\fR(1)
- to be the name of the host, a colon, and the full current working directory.
- A fancier way to do that is
- .IP "" 4
- > alias cwdcmd 'echo \-n "^[]2;${HOST}:$cwd^G^[]1;${HOST}^G"'
- .PP
- This will put the hostname and working directory on the title bar but
- only the hostname in the icon manager menu.
- .PP
- Note that putting a \fIcd\fR, \fIpushd\fR or \fIpopd\fR in \fIcwdcmd\fR
- may cause an infinite loop. It is the author's opinion that anyone doing
- so will get what they deserve.
- .RE
- .TP 8
- .B jobcmd
- Runs before each command gets executed, or when the command changes state.
- This is similar to \fIpostcmd\fR, but it does not print builtins.
- .RS +8
- .IP "" 4
- > alias jobcmd 'echo \-n "^[]2\e;\e!#:q^G"'
- .PP
- then executing \fIvi foo.c\fR will put the command string in the xterm title bar.
- .RE
- .TP 8
- .B helpcommand
- Invoked by the \fBrun-help\fR editor command. The command name for which help
- is sought is passed as sole argument.
- For example, if one does
- .RS +8
- .IP "" 4
- > alias helpcommand '\e!:1 --help'
- .PP
- then the help display of the command itself will be invoked, using the GNU
- help calling convention.
- Currently there is no easy way to account for various calling conventions (e.g.,
- the customary Unix `-h'), except by using a table of many commands.
- .RE
- .TP 8
- .B periodic
- Runs every \fBtperiod\fR minutes. This provides a convenient means for
- checking on common but infrequent changes such as new mail. For example,
- if one does
- .RS +8
- .IP "" 4
- > set tperiod = 30
- .br
- > alias periodic checknews
- .PP
- then the \fIchecknews\fR(1) program runs every 30 minutes.
- If \fIperiodic\fR is set but \fBtperiod\fR is unset or set to 0,
- \fIperiodic\fR behaves like \fIprecmd\fR.
- .RE
- .TP 8
- .B precmd
- Runs just before each prompt is printed. For example, if one does
- .RS +8
- .IP "" 4
- > alias precmd date
- .PP
- then \fIdate\fR(1) runs just before the shell prompts for each command.
- There are no limits on what \fIprecmd\fR can be set to do, but discretion
- should be used.
- .RE
- .TP 8
- .B postcmd
- Runs before each command gets executed.
- .RS +8
- .IP "" 4
- > alias postcmd 'echo \-n "^[]2\e;\e!#:q^G"'
- .PP
- then executing \fIvi foo.c\fR will put the command string in the xterm title bar.
- .RE
- .TP 8
- .B shell
- Specifies the interpreter for executable scripts which do not themselves
- specify an interpreter. The first word should be a full path name to the
- desired interpreter (e.g., `/bin/csh' or `/usr/local/bin/tcsh').
- .SS "Special shell variables"
- The variables described in this section have special meaning to the shell.
- .PP
- The shell sets \fBaddsuffix\fR, \fBargv\fR, \fBautologout\fR, \fBcsubstnonl\fR, \fBcommand\fR, \fBecho_style\fR,
- \fBedit\fR, \fBgid\fR, \fBgroup\fR, \fBhome\fR, \fBloginsh\fR, \fBoid\fR, \fBpath\fR,
- \fBprompt\fR, \fBprompt2\fR, \fBprompt3\fR, \fBshell\fR, \fBshlvl\fR,
- \fBtcsh\fR, \fBterm\fR, \fBtty\fR, \fBuid\fR, \fBuser\fR and \fBversion\fR at
- startup; they do not change thereafter unless changed by the user. The shell
- updates \fBcwd\fR, \fBdirstack\fR, \fBowd\fR and \fBstatus\fR when necessary,
- and sets \fBlogout\fR on logout.
- .PP
- The shell synchronizes \fBgroup\fR, \fBhome\fR, \fBpath\fR, \fBshlvl\fR,
- \fBterm\fR and \fBuser\fR 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 \fBcwd\fR and \fBPWD\fR have identical meanings, they
- are not synchronized in this manner, and that the shell automatically
- interconverts the different formats of \fBpath\fR and \fBPATH\fR.
- .TP 8
- .B addsuffix \fR(+)
- 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.
- .TP 8
- .B afsuser \fR(+)
- If set, \fBautologout\fR's autolock feature uses its value instead of
- the local username for kerberos authentication.
- .TP 8
- .B ampm \fR(+)
- If set, all times are shown in 12-hour AM/PM format.
- .TP 8
- .B argv
- The arguments to the shell. Positional parameters are taken from \fBargv\fR,
- i.e., `$1' is replaced by `$argv[1]', etc.
- Set by default, but usually empty in interactive shells.
- .TP 8
- .B autocorrect \fR(+)
- If set, the \fIspell-word\fR editor command is invoked automatically before
- each completion attempt.
- .TP 8
- .B autoexpand \fR(+)
- If set, the \fIexpand-history\fR editor command is invoked automatically
- before each completion attempt. If this is set to \fIonlyhistory\fR, then
- only history will be expanded and a second completion will expand filenames.
- .TP 8
- .B autolist \fR(+)
- 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.
- .TP 8
- .B autologout \fR(+)
- 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 \fBlogout\fR 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 \fBDISPLAY\fR environment variable is set),
- the tty is a pseudo-tty (pty) or the shell was not so compiled (see the
- \fBversion\fR shell variable).
- See also the \fBafsuser\fR and \fBlogout\fR shell variables.
- .TP 8
- .B autorehash \fR(+)
- If set, the internal hash table of the contents of the directories in the
- \fBpath\fR variable will be recomputed if a command is not found in the hash
- table. In addition, the list of available commands will be rebuilt for each
- command completion or spelling correction attempt if set to `complete' or
- `correct' respectively; if set to `always', this will be done for both
- cases.
- .TP 8
- .B backslash_quote \fR(+)
- If set, backslashes (`\\') always quote `\\', `'', and `"'. This may make
- complex quoting tasks easier, but it can cause syntax errors in \fIcsh\fR(1)
- scripts.
- .TP 8
- .B catalog
- The file name of the message catalog.
- If set, tcsh use `tcsh.${catalog}' as a message catalog instead of
- default `tcsh'.
- .TP 8
- .B cdpath
- A list of directories in which \fIcd\fR should search for
- subdirectories if they aren't found in the current directory.
- .TP 8
- .B color
- If set, it enables color display for the builtin \fBls\-F\fR and it passes
- \fB\-\-color=auto\fR to \fBls\fR. Alternatively, it can be set to only
- \fBls\-F\fR or only \fBls\fR to enable color to only one command. Setting
- it to nothing is equivalent to setting it to \fB(ls\-F ls)\fR.
- .TP 8
- .B colorcat
- If set, it enables color escape sequence for NLS message files.
- And display colorful NLS messages.
- .TP 8
- .B command \fR(+)
- If set, the command which was passed to the shell with the \fB-c\fR flag (q.v.).
- .TP 8
- .B compat_expr \fR(+)
- If set, the shell will evaluate expressions right to left, like the original
- \fIcsh\fR.
- .TP 8
- .B complete \fR(+)
- If set to `igncase', the completion becomes case insensitive.
- If set to `enhance', completion ignores case and considers
- hyphens and underscores to be equivalent; it will also treat
- periods, hyphens and underscores (`.', `\-' and `_') as word
- separators.
- If set to `Enhance', completion matches uppercase and underscore
- characters explicitly and matches lowercase and hyphens in a
- case-insensivite manner; it will treat periods, hypens and underscores
- as word separators.
- .TP 8
- .B continue \fR(+)
- If set to a list of commands, the shell will continue the listed
- commands, instead of starting a new one.
- .TP 8
- .B continue_args \fR(+)
- Same as continue, but the shell will execute:
- .RS +8
- .IP "" 4
- echo `pwd` $argv > ~/.<cmd>_pause; %<cmd>
- .RE
- .TP 8
- .B correct \fR(+)
- 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.
- .TP 8
- .B csubstnonl \fR(+)
- If set, newlines and carriage returns in command substitution are
- replaced by spaces. Set by default.
- .TP 8
- .B cwd
- The full pathname of the current directory.
- See also the \fBdirstack\fR and \fBowd\fR shell variables.
- .TP 8
- .B dextract \fR(+)
- If set, `pushd +\fIn\fR' extracts the \fIn\fRth directory from the directory
- stack rather than rotating it to the top.
- .TP 8
- .B dirsfile \fR(+)
- The default location in which `dirs \-S' and `dirs \-L' look for
- a history file. If unset, \fI~/.cshdirs\fR is used.
- Because only \fI~/.tcshrc\fR is normally sourced before \fI~/.cshdirs\fR,
- \fBdirsfile\fR should be set in \fI~/.tcshrc\fR rather than \fI~/.login\fR.
- .TP 8
- .B dirstack \fR(+)
- 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 \fBdirstack\fR,
- but the first element (the current working directory) is always correct.
- See also the \fBcwd\fR and \fBowd\fR shell variables.
- .TP 8
- .B dspmbyte \fR(+)
- Has an effect iff 'dspm' is listed as part of the \fBversion\fR shell variable.
- If set to `euc', it enables display and editing EUC-kanji(Japanese) code.
- If set to `sjis', it enables display and editing Shift-JIS(Japanese) code.
- If set to `big5', it enables display and editing Big5(Chinese) code.
- If set to `utf8', it enables display and editing Utf8(Unicode) code.
- If set to the following format, it enables display and editing of original
- multi-byte code format:
- .RS +8
- .IP "" 4
- > set dspmbyte = 0000....(256 bytes)....0000
- .PP
- The table requires \fBjust\fR 256 bytes. Each character of 256 characters
- corresponds (from left to right) to the ASCII codes 0x00, 0x01, ... 0xff. Each
- character
- .\" (position in this table?)
- is set to number 0,1,2 and 3. Each number has the following meaning:
- .br
- 0 ... not used for multi-byte characters.
- .br
- 1 ... used for the first byte of a multi-byte character.
- .br
- 2 ... used for the second byte of a multi-byte character.
- .br
- 3 ... used for both the first byte and second byte of a multi-byte character.
- .\" SHK: I tried my best to get the following to be grammatically correct.
- .\" However, I still don't understand what's going on here. In the
- .\" following example, there are three bytes, but the text seems to refer to
- .\" each nybble as a character. What's going on here? It this 3-byte code
- .\" in the table? The text above seems to imply that there are 256
- .\" characters/bytes in the table. If I get some more info on this (perhaps
- .\" a complete example), I could fix the text to be grammatically correct.
- .\" (steve.kelem@xilinx.com 1999/09/13)
- .PP
- Example:
- .br
- If set to `001322', the first character (means 0x00 of the ASCII code) and
- second character (means 0x01 of ASCII code) are set to `0'. Then, it is not
- used for multi-byte characters. The 3rd character (0x02) is set to '1',
- indicating that it is used for the first byte of a multi-byte character.
- The 4th character(0x03) is set '3'. It is used for both the first byte and
- the second byte of a multi-byte character. The 5th and 6th characters
- (0x04,0x05) are set to '2', indicating that they are used for the second
- byte of a multi-byte character.
- .PP
- The GNU fileutils version of ls cannot display multi-byte
- filenames without the -N ( --literal ) option. If you are using
- this version, set the second word of dspmbyte to "ls". If not, for
- example, "ls-F -l" cannot display multi-byte filenames.
- .PP
- Note:
- .br
- This variable can only be used if KANJI and DSPMBYTE has been defined at
- compile time.
- .RE
- .TP 8
- .B dunique \fR(+)
- If set, \fIpushd\fR removes any instances of \fIname\fR
- from the stack before pushing it onto the stack.
- .TP 8
- .B 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, because these substitutions are then done selectively.
- Set by the \fB\-x\fR command line option.
- .TP 8
- .B echo_style \fR(+)
- The style of the \fIecho\fR builtin. May be set to
- .PP
- .RS +8
- .PD 0
- .TP 8
- bsd
- Don't echo a newline if the first argument is `\-n'.
- .TP 8
- sysv
- Recognize backslashed escape sequences in echo strings.
- .TP 8
- both
- Recognize both the `\-n' flag and backslashed escape sequences; the default.
- .TP 8
- none
- Recognize neither.
- .PD
- .PP
- Set by default to the local system default. The BSD and System V
- options are described in the \fIecho\fR(1) man pages on the appropriate
- systems.
- .RE
- .TP 8
- .B edit \fR(+)
- If set, the command-line editor is used. Set by default in interactive
- shells.
- .TP 8
- .B ellipsis \fR(+)
- If set, the `%c'/`%.' and `%C' prompt sequences (see the \fBprompt\fR
- shell variable) indicate skipped directories with an ellipsis (`...')
- instead of `/<skipped>'.
- .TP 8
- .B euid \fR(+)
- The user's effective user ID.
- .TP 8
- .B euser \fR(+)
- The first matching passwd entry name corresponding to the effective user ID.
- .TP 8
- .B fignore \fR(+)
- Lists file name suffixes to be ignored by completion.
- .TP 8
- .B filec
- In \fItcsh\fR, completion is always used and this variable is ignored
- by default. If
- .B edit
- is unset, then the traditional \fIcsh\fR completion is used.
- If set in \fIcsh\fR, filename completion is used.
- .TP 8
- .B gid \fR(+)
- The user's real group ID.
- .TP 8
- .B globdot \fR(+)
- If set, wild-card glob patterns will match files and directories beginning
- with `.' except for `.' and `..'
- .TP 8
- .B globstar \fR(+)
- If set, the `**' and `***' file glob patterns will match any string of
- characters including `/' traversing any existing sub-directories. (e.g.
- `ls **.c' will list all the .c files in the current directory tree).
- If used by itself, it will match match zero or more sub-directories
- (e.g. `ls /usr/include/**/time.h' will list any file named `time.h'
- in the /usr/include directory tree; whereas `ls /usr/include/**time.h'
- will match any file in the /usr/include directory tree ending in `time.h').
- To prevent problems with recursion, the `**' glob-pattern will not
- descend into a symbolic link containing a directory. To override this,
- use `***'
- .TP 8
- .B group \fR(+)
- The user's group name.
- .TP 8
- .B highlight
- If set, the incremental search match (in \fIi-search-back\fR and
- \fIi-search-fwd\fR) and the region between the mark and the cursor are
- highlighted in reverse video.
- .IP "" 8
- Highlighting requires more frequent terminal writes, which introduces extra
- overhead. If you care about terminal performance, you may want to leave this
- unset.
- .TP 8
- .B histchars
- A string value determining the characters used in \fBHistory
- substitution\fR (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.
- .TP 8
- .B histdup \fR(+)
- 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. Note that the
- `prev' and `all' options renumber history events so there are no gaps.
- .TP 8
- .B histfile \fR(+)
- The default location in which `history \-S' and `history \-L' look for
- a history file. If unset, \fI~/.history\fR is used. \fBhistfile\fR is
- useful when sharing the same home directory between different machines,
- or when saving separate histories on different terminals. Because only
- \fI~/.tcshrc\fR is normally sourced before \fI~/.history\fR,
- \fBhistfile\fR should be set in \fI~/.tcshrc\fR rather than
- \fI~/.login\fR.
- .TP 8
- .B histlit \fR(+)
- If set, builtin and editor commands and the \fBsavehist\fR mechanism
- use the literal (unexpanded) form of lines in the history list. See
- also the \fItoggle-literal-history\fR editor command.
- .TP 8
- .B 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 \fBprompt\fR; note the variable meaning of
- `%R'. Set to `100' by default.
- .TP 8
- .B home
- Initialized to the home directory of the invoker. The filename
- expansion of `\fI~\fR' refers to this variable.
- .TP 8
- .B ignoreeof
- If set to the empty string or `0' and the input device is a terminal,
- the \fIend-of-file\fR 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. Historically this setting exited after 26 successive
- EOF's to avoid infinite loops. If set to a number \fIn\fR, the shell
- ignores \fIn - 1\fR consecutive \fIend-of-file\fRs and exits on the
- \fIn\fRth. (+) If unset, `1' is used, i.e., the shell exits on a
- single `^D'.
- .TP 8
- .B implicitcd \fR(+)
- If set, the shell treats a directory name typed as a command as though
- it were a request to change to that directory. If set to \fIverbose\fR,
- the change of directory is echoed to the standard output. This behavior
- is inhibited in non-interactive shell scripts, or for command strings
- with more than one word. Changing directory takes precedence over
- executing a like-named command, but it is done after alias
- substitutions. Tilde and variable expansions work as expected.
- .TP 8
- .B inputmode \fR(+)
- If set to `insert' or `overwrite', puts the editor into that input mode
- at the beginning of each line.
- .TP 8
- .B killdup \fR(+)
- Controls handling of duplicate entries in the kill ring. If set to
- `all' only unique strings are entered in the kill ring. If set to
- `prev' and the last killed string is the same as the current killed
- string, then the current string is not entered in the ring. If set
- to `erase' and the same string is found in the kill ring, the old
- string is erased and the current one is inserted.
- .TP 8
- .B killring \fR(+)
- Indicates the number of killed strings to keep in memory. Set to `30'
- by default. If unset or set to less than `2', the shell will only
- keep the most recently killed string.
- Strings are put in the killring by the editor commands that delete
- (kill) strings of text, e.g. \fIbackward-delete-word\fR,
- \fIkill-line\fR, etc, as well as the \fIcopy-region-as-kill\fR command.
- The \fIyank\fR editor command will yank the most recently killed string
- into the command-line, while \fIyank-pop\fR (see \fBEditor commands\fR)
- can be used to yank earlier killed strings.
- .TP 8
- .B listflags \fR(+)
- If set to `x', `a' or `A', or any combination thereof (e.g., `xA'), they
- are used as flags to \fIls\-F\fR, 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
- \fBlistflags\fR is set, it is used as the path to `ls(1)'.
- .TP 8
- .B listjobs \fR(+)
- If set, all jobs are listed when a job is suspended. If set to `long',
- the listing is in long format.
- .TP 8
- .B listlinks \fR(+)
- If set, the \fIls\-F\fR builtin command shows the type of file to which
- each symbolic link points.
- .TP 8
- .B listmax \fR(+)
- The maximum number of items which the \fIlist-choices\fR editor command
- will list without asking first.
- .TP 8
- .B listmaxrows \fR(+)
- The maximum number of rows of items which the \fIlist-choices\fR editor
- command will list without asking first.
- .TP 8
- .B loginsh \fR(+)
- Set by the shell if it is a login shell. Setting or unsetting it
- within a shell has no effect. See also \fBshlvl\fR.
- .TP 8
- .B logout \fR(+)
- 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 \fBSignal handling\fR). See also the \fBautologout\fR
- shell variable.
- .TP 8
- .B mail
- A list of files and directories to check for incoming mail, optionally
- preceded 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 \fBmail\fR contains multiple files, `You have
- new mail in \fIname\fR.') if the filesize is greater than zero in size
- and has a modification time greater than its access time.
- .PP
- .RS +8
- .PD
- .PP
- 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, to prevent
- redundant notifications. Most login programs will tell you whether or not
- you have mail when you log in.
- .PP
- If a file specified in \fBmail\fR is a directory, the shell will count each
- file within that directory as a separate message, and will report `You have
- \fIn\fR mails.' or `You have \fIn\fR mails in \fIname\fR.' as appropriate.
- This functionality is provided primarily for those systems which store mail
- in this manner, such as the Andrew Mail System.
- .PP
- If the first word of \fBmail\fR is numeric it is taken as a different mail
- checking interval, in seconds.
- .PP
- Under very rare circumstances, the shell may report `You have mail.' instead
- of `You have new mail.'
- .RE
- .TP 8
- .B matchbeep \fR(+)
- 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.
- .TP 8
- .B nobeep \fR(+)
- If set, beeping is completely disabled.
- See also \fBvisiblebell\fR.
- .TP 8
- .B 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 \fBInput/output\fR section.
- .TP 8
- .B noding
- If set, disable the printing of `DING!' in the \fBprompt\fR time
- specifiers at the change of hour.
- .TP 8
- .B noglob
- If set, \fBFilename substitution\fR and \fBDirectory stack substitution\fR
- (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.
- .TP 8
- .B nokanji \fR(+)
- If set and the shell supports Kanji (see the \fBversion\fR shell variable),
- it is disabled so that the meta key can be used.
- .TP 8
- .B nonomatch
- If set, a \fBFilename substitution\fR or \fBDirectory stack substitution\fR
- (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.
- .TP 8
- .B nostat \fR(+)
- A list of directories (or glob-patterns which match directories; see
- \fBFilename substitution\fR) that should not be \fIstat\fR(2)ed during a
- completion operation. This is usually used to exclude directories which
- take too much time to \fIstat\fR(2), for example \fI/afs\fR.
- .TP 8
- .B notify
- If set, the shell announces job completions asynchronously.
- The default is to present job completions just before printing a prompt.
- .TP 8
- .B oid \fR(+)
- The user's real organization ID. (Domain/OS only)
- .TP 8
- .B owd \fR(+)
- The old working directory, equivalent to the `\-' used by \fIcd\fR and \fIpushd\fR.
- See also the \fBcwd\fR and \fBdirstack\fR shell variables.
- .TP 8
- .B padhour
- If set, enable the printing of padding '0' for hours, in 24 and 12 hour
- formats. E.G.: 07:45:42 vs. 7:45:42.
- .TP 8
- .B parseoctal
- To retain compatibily with older versions numeric variables starting with
- 0 are not interpreted as octal. Setting this variable enables proper octal
- parsing.
- .TP 8
- .B path
- A list of directories in which to look for executable commands.
- A null word specifies the current directory.
- If there is no \fBpath\fR variable then only full path names will execute.
- \fBpath\fR is set by the shell at startup from the \fBPATH\fR environment
- variable or, if \fBPATH\fR 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 \fBpath\fR or omit it entirely
- depending on how it was compiled; see the \fBversion\fR shell variable.
- A shell which is given neither the \fB\-c\fR nor the \fB\-t\fR option
- hashes the contents of the directories in \fBpath\fR after
- reading \fI~/.tcshrc\fR and each time \fBpath\fR is reset.
- If one adds a new command to a directory in \fBpath\fR while the shell
- is active, one may need to do a \fIrehash\fR for the shell to find it.
- .TP 8
- .B printexitvalue \fR(+)
- If set and an interactive program exits with a non-zero status, the shell
- prints `Exit \fBstatus\fR'.
- .TP 8
- .B prompt
- The string which is printed before reading each command from the terminal.
- \fBprompt\fR may include any of the following formatting sequences (+), which
- are replaced by the given information:
- .PP
- .RS +8
- .PD 0
- .TP 4
- %/
- The current working directory.
- .TP 4
- %~
- The current working directory, but with one's home directory
- represented by `~' and other users' home directories represented by
- `~user' as per \fBFilename substitution\fR. `~user' substitution
- happens only if the shell has already used `~\fIuser\fR' in a pathname
- in the current session.
- .TP 4
- %c[[0]\fIn\fR], %.[[0]\fIn\fR]
- The trailing component of the current working directory, or \fIn\fR
- trailing components if a digit \fIn\fR is given.
- If \fIn\fR begins with `0', the number of skipped components precede
- the trailing component(s) in the format `/<\fIskipped\fR>trailing'.
- If the \fBellipsis\fR 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.
- .TP 4
- %C
- Like %c, but without `~' substitution.
- .TP 4
- %h, %!, !
- The current history event number.
- .TP 4
- %M
- The full hostname.
- .TP 4
- %m
- The hostname up to the first `.'.
- .TP 4
- %S (%s)
- Start (stop) standout mode.
- .TP 4
- %B (%b)
- Start (stop) boldfacing mode.
- .TP 4
- %U (%u)
- Start (stop) underline mode.
- .TP 4
- %t, %@
- The time of day in 12-hour AM/PM format.
- .TP 4
- %T
- Like `%t', but in 24-hour format (but see the \fBampm\fR shell variable).
- .TP 4
- %p
- The `precise' time of day in 12-hour AM/PM format, with seconds.
- .TP 4
- %P
- Like `%p', but in 24-hour format (but see the \fBampm\fR shell variable).
- .TP 4
- \e\fIc\fR
- \fIc\fR is parsed as in \fIbindkey\fR.
- .TP 4
- ^\fIc\fR
- \fIc\fR is parsed as in \fIbindkey\fR.
- .TP 4
- %%
- A single `%'.
- .TP 4
- %n
- The user name.
- .TP 4
- %N
- The effective user name.
- .TP 4
- %j
- The number of jobs.
- .TP 4
- %d
- The weekday in `Day' format.
- .TP 4
- %D
- The day in `dd' format.
- .TP 4
- %w
- The month in `Mon' format.
- .TP 4
- %W
- The month in `mm' format.
- .TP 4
- %y
- The year in `yy' format.
- .TP 4
- %Y
- The year in `yyyy' format.
- .TP 4
- %l
- The shell's tty.
- .TP 4
- %L
- Clears from the end of the prompt to end of the display or the end of the line.
- .TP 4
- %$
- Expands the shell or environment variable name immediately after the `$'.
- .TP 4
- %#
- `>' (or the first character of the \fBpromptchars\fR shell variable)
- for normal users, `#' (or the second character of \fBpromptchars\fR)
- for the superuser.
- .TP 4
- %{\fIstring\fR%}
- Includes \fIstring\fR 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 \fBprompt\fR.
- .TP 4
- %?
- The return code of the command executed just before the prompt.
- .TP 4
- %R
- In \fBprompt2\fR, the status of the parser.
- In \fBprompt3\fR, the corrected string.
- In \fBhistory\fR, the history string.
- .PD
- .PP
- `%B', `%S', `%U' and `%{\fIstring\fR%}' are available in only
- eight-bit-clean shells; see the \fBversion\fR shell variable.
- .PP
- The bold, standout and underline sequences are often used to distinguish a
- superuser shell. For example,
- .IP "" 4
- > set prompt = "%m [%h] %B[%@]%b [%/] you rang? "
- .br
- tut [37] \fB[2:54pm]\fR [/usr/accts/sys] you rang? _
- .PP
- If `%t', `%@', `%T', `%p', or `%P' is used, and \fBnoding\fR is not set,
- then print `DING!' on the change of hour (i.e, `:00' minutes) instead of
- the actual time.
- .PP
- Set by default to `%# ' in interactive shells.
- .RE
- .TP 8
- .B prompt2 \fR(+)
- The string with which to prompt in \fIwhile\fR and \fIforeach\fR loops and
- after lines ending in `\\'.
- The same format sequences may be used as in \fBprompt\fR (q.v.);
- note the variable meaning of `%R'.
- Set by default to `%R? ' in interactive shells.
- .TP 8
- .B prompt3 \fR(+)
- The string with which to prompt when confirming automatic spelling correction.
- The same format sequences may be used as in \fBprompt\fR (q.v.);
- note the variable meaning of `%R'.
- Set by default to `CORRECT>%R (y|n|e|a)? ' in interactive shells.
- .TP 8
- .B promptchars \fR(+)
- If set (to a two-character string), the `%#' formatting sequence in the
- \fBprompt\fR shell variable is replaced with the first character for
- normal users and the second character for the superuser.
- .TP 8
- .B pushdtohome \fR(+)
- If set, \fIpushd\fR without arguments does `pushd ~', like \fIcd\fR.
- .TP 8
- .B pushdsilent \fR(+)
- If set, \fIpushd\fR and \fIpopd\fR do not print the directory stack.
- .TP 8
- .B recexact \fR(+)
- If set, completion completes on an exact match even if a longer match is
- possible.
- .TP 8
- .B recognize_only_executables \fR(+)
- If set, command listing displays only files in the path that are
- executable. Slow.
- .TP 8
- .B rmstar \fR(+)
- If set, the user is prompted before `rm *' is executed.
- .TP 8
- .B rprompt \fR(+)
- The string to print on the right-hand side of the screen (after
- the command input) when the prompt is being displayed on the left.
- It recognizes the same formatting characters as \fBprompt\fR.
- It will automatically disappear and reappear as necessary, to ensure that
- command input isn't obscured, and will appear only if the prompt,
- command input, and itself will fit together on the first line.
- If \fBedit\fR isn't set, then \fBrprompt\fR will be printed after
- the prompt and before the command input.
- .TP 8
- .B savedirs \fR(+)
- If set, the shell does `dirs \-S' before exiting.
- If the first word is set to a number, at most that many directory stack
- entries are saved.
- .TP 8
- .B 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 \fBhistory\fR.)
- 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. (+)
- .TP 8
- .B sched \fR(+)
- The format in which the \fIsched\fR builtin command prints scheduled events;
- if not given, `%h\\t%T\\t%R\\n' is used.
- The format sequences are described above under \fBprompt\fR;
- note the variable meaning of `%R'.
- .TP 8
- .B 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 \fBBuiltin and non-builtin command execution\fR.) Initialized to the
- (system-dependent) home of the shell.
- .TP 8
- .B shlvl \fR(+)
- The number of nested shells.
- Reset to 1 in login shells.
- See also \fBloginsh\fR.
- .TP 8
- .B status
- The status returned by the last command, unless the variable
- .B anyerror
- is set, and any error in a pipeline or a backquote expansion will be
- propagated (this is the default
- .B csh
- behavior, and the current
- .B tcsh
- default). 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'.
- .TP 8
- .B symlinks \fR(+)
- Can be set to several different values to control symbolic link (`symlink')
- resolution:
- .RS +8
- .PP
- 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.
- .PP
- 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 \fIcd\fRing through a symbolic link and then `cd ..'ing
- returns one to the original directory. This affects only builtin commands
- and filename completion.
- .PP
- 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 \fInormalize-path\fR (bound by default to ^X-n) when necessary.
- .PP
- Some examples are in order. First, let's set up some play directories:
- .IP "" 4
- > cd /tmp
- .br
- > mkdir from from/src to
- .br
- > ln \-s from/src to/dst
- .PP
- Here's the behavior with \fBsymlinks\fR unset,
- .IP "" 4
- > cd /tmp/to/dst; echo $cwd
- .br
- /tmp/to/dst
- .br
- > cd ..; echo $cwd
- .br
- /tmp/from
- .PP
- here's the behavior with \fBsymlinks\fR set to `chase',
- .IP "" 4
- > cd /tmp/to/dst; echo $cwd
- .br
- /tmp/from/src
- .br
- > cd ..; echo $cwd
- .br
- /tmp/from
- .PP
- here's the behavior with \fBsymlinks\fR set to `ignore',
- .IP "" 4
- > cd /tmp/to/dst; echo $cwd
- .br
- /tmp/to/dst
- .br
- > cd ..; echo $cwd
- .br
- /tmp/to
- .PP
- and here's the behavior with \fBsymlinks\fR set to `expand'.
- .IP "" 4
- > cd /tmp/to/dst; echo $cwd
- .br
- /tmp/to/dst
- .br
- > cd ..; echo $cwd
- .br
- /tmp/to
- .br
- > cd /tmp/to/dst; echo $cwd
- .br
- /tmp/to/dst
- .br
- > cd ".."; echo $cwd
- .br
- /tmp/from
- .br
- > /bin/echo ..
- .br
- /tmp/to
- .br
- > /bin/echo ".."
- .br
- \&..
- .PP
- Note that `expand' expansion 1) works just like `ignore' for builtins
- like \fIcd\fR, 2) is prevented by quoting, and 3) happens before
- filenames are passed to non-builtin commands.
- .RE
- .TP 8
- .B tcsh \fR(+)
- 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.
- .TP 8
- .B term
- The terminal type. Usually set in \fI~/.login\fR as described under
- \fBStartup and shutdown\fR.
- .TP 8
- .B time
- If set to a number, then the \fItime\fR 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 \fItime\fR builtin. (u) The following sequences may be used in the
- format string:
- .PP
- .RS +8
- .PD 0
- .TP 4
- %U
- The time the process spent in user mode in cpu seconds.
- .TP 4
- %S
- The time the process spent in kernel mode in cpu seconds.
- .TP 4
- %E
- The elapsed (wall clock) time in seconds.
- .TP 4
- %P
- The CPU percentage computed as (%U + %S) / %E.
- .TP 4
- %W
- Number of times the process was swapped.
- .TP 4
- %X
- The average amount in (shared) text space used in Kbytes.
- .TP 4
- %D
- The average amount in (unshared) data/stack space used in Kbytes.
- .TP 4
- %K
- The total space used (%X + %D) in Kbytes.
- .TP 4
- %M
- The maximum memory the process had in use at any time in Kbytes.
- .TP 4
- %F
- The number of major page faults (page needed to be brought from disk).
- .TP 4
- %R
- The number of minor page faults.
- .TP 4
- %I
- The number of input operations.
- .TP 4
- %O
- The number of output operations.
- .TP 4
- %r
- The number of socket messages received.
- .TP 4
- %s
- The number of socket messages sent.
- .TP 4
- %k
- The number of signals received.
- .TP 4
- %w
- The number of voluntary context switches (waits).
- .TP 4
- %c
- The number of involuntary context switches.
- .PD
- .PP
- 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.
- .PP
- Under Sequent's DYNIX/ptx, %X, %D, %K, %r and %s are not
- available, but the following additional sequences are:
- .PP
- .PD 0
- .TP 4
- %Y
- The number of system calls performed.
- .TP 4
- %Z
- The number of pages which are zero-filled on demand.
- .TP 4
- %i
- The number of times a process's resident set size was increased by the kernel.
- .TP 4
- %d
- The number of times a process's resident set size was decreased by the kernel.
- .TP 4
- %l
- The number of read system calls performed.
- .TP 4
- %m
- The number of write system calls performed.
- .TP 4
- %p
- The number of reads from raw disk devices.
- .TP 4
- %q
- The number of writes to raw disk devices.
- .PD
- .PP
- 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.
- .RE
- .TP 8
- .B tperiod \fR(+)
- The period, in minutes, between executions of the \fIperiodic\fR special alias.
- .TP 8
- .B tty \fR(+)
- The name of the tty, or empty if not attached to one.
- .TP 8
- .B uid \fR(+)
- The user's real user ID.
- .TP 8
- .B user
- The user's login name.
- .TP 8
- .B verbose
- If set, causes the words of each
- command to be printed, after history substitution (if any).
- Set by the \fB\-v\fR command line option.
- .TP 8
- .B version \fR(+)
- The version ID stamp. It contains the shell's version number (see \fBtcsh\fR),
- origin, release date, vendor, operating system and machine (see \fBVENDOR\fR,
- \fBOSTYPE\fR and \fBMACHTYPE\fR) and a comma-separated
- list of options which were set at compile time.
- Options which are set by default in the distribution are noted.
- .PP
- .RS +8
- .PD 0
- .TP 6
- 8b
- The shell is eight bit clean; default
- .TP 6
- 7b
- The shell is not eight bit clean
- .TP 6
- wide
- The shell is multibyte encoding clean (like UTF-8)
- .TP 6
- nls
- The system's NLS is used; default for systems with NLS
- .TP 6
- lf
- Login shells execute \fI/etc/csh.login\fR before instead of after
- \fI/etc/csh.cshrc\fR and \fI~/.login\fR before instead of after
- \fI~/.tcshrc\fR and \fI~/.history\fR.
- .TP 6
- dl
- `.' is put last in \fBpath\fR for security; default
- .TP 6
- nd
- `.' is omitted from \fBpath\fR for security
- .TP 6
- vi
- \fIvi\fR-style editing is the default rather than \fIemacs\fR
- .TP 6
- dtr
- Login shells drop DTR when exiting
- .TP 6
- bye
- \fIbye\fR is a synonym for \fIlogout\fR and \fIlog\fR
- is an alternate name for \fIwatchlog\fR
- .TP 6
- al
- \fBautologout\fR is enabled; default
- .TP 6
- kan
- Kanji is used if appropriate according to locale settings,
- unless the \fBnokanji\fR shell variable is set
- .TP 6
- sm
- The system's \fImalloc\fR(3) is used
- .TP 6
- hb
- The `#!<program> <args>' convention is emulated when executing shell scripts
- .TP 6
- ng
- The \fInewgrp\fR builtin is available
- .TP 6
- rh
- The shell attempts to set the \fBREMOTEHOST\fR environment variable
- .TP 6
- afs
- The shell verifies your password with the kerberos server if local
- authentication fails. The \fBafsuser\fR shell variable or the
- \fBAFSUSER\fR environment variable override your local username if set.
- .PD
- .PP
- An administrator may enter additional strings to indicate differences
- in the local version.
- .RE
- .TP 8
- .B visiblebell \fR(+)
- If set, a screen flash is used rather than the audible bell.
- See also \fBnobeep\fR.
- .TP 8
- .B watch \fR(+)
- 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 \fBwatch\fR to `(any any)' watches all users and terminals.
- For example,
- .RS +8
- .IP "" 4
- set watch = (george ttyd1 any console $user any)
- .PP
- reports activity of the user `george' on ttyd1, any user on the console, and
- oneself (or a trespasser) on any terminal.
- .PP
- Logins and logouts are checked every 10 minutes by default, but the first
- word of \fBwatch\fR can be set to a number to check every so many minutes.
- For example,
- .IP "" 4
- set watch = (1 any any)
- .PP
- reports any login/logout once every minute. For the impatient, the \fIlog\fR
- builtin command triggers a \fBwatch\fR report at any time. All current logins
- are reported (as with the \fIlog\fR builtin) when \fBwatch\fR is first set.
- .PP
- The \fBwho\fR shell variable controls the format of \fBwatch\fR reports.
- .RE
- .TP 8
- .B who \fR(+)
- The format string for \fBwatch\fR messages. The following sequences
- are replaced by the given information:
- .PP
- .RS +8
- .PD 0
- .TP 4
- %n
- The name of the user who logged in/out.
- .TP 4
- %a
- The observed action, i.e., `logged on', `logged off' or `replaced \fIolduser\fR on'.
- .TP 4
- %l
- The terminal (tty) on which the user logged in/out.
- .TP 4
- %M
- The full hostname of the remote host, or `local' if the login/logout was
- from the local host.
- .TP 4
- %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.
- .PD
- .PP
- %M and %m are available on only systems that store the remote hostname in
- \fI/etc/utmp\fR.
- If unset, `%n has %a %l from %m.' is used, or `%n has %a %l.' on systems
- which don't store the remote hostname.
- .RE
- .TP 8
- .B wordchars \fR(+)
- A list of non-alphanumeric characters to be considered part of a word by the
- \fIforward-word\fR, \fIbackward-word\fR etc., editor commands.
- If unset, `*?_\-.[]~=' is used.
- .SH ENVIRONMENT
- .TP 8
- .B AFSUSER \fR(+)
- Equivalent to the \fBafsuser\fR shell variable.
- .TP 8
- .B COLUMNS
- The number of columns in the terminal. See \fBTerminal management\fR.
- .TP 8
- .B DISPLAY
- Used by X Window System (see \fIX\fR(1)).
- If set, the shell does not set \fBautologout\fR (q.v.).
- .TP 8
- .B EDITOR
- The pathname to a default editor.
- See also the \fBVISUAL\fR environment variable
- and the \fIrun-fg-editor\fR editor command.
- .TP 8
- .B GROUP \fR(+)
- Equivalent to the \fBgroup\fR shell variable.
- .TP 8
- .B HOME
- Equivalent to the \fBhome\fR shell variable.
- .TP 8
- .B HOST \fR(+)
- Initialized to the name of the machine on which the shell
- is running, as determined by the \fIgethostname\fR(2) system call.
- .TP 8
- .B HOSTTYPE \fR(+)
- Initialized to the type of machine on which the shell
- is running, as determined at compile time. This variable is obsolete and
- will be removed in a future version.
- .TP 8
- .B HPATH \fR(+)
- A colon-separated list of directories in which the \fIrun-help\fR editor
- command looks for command documentation.
- .TP 8
- .B LANG
- Gives the preferred character environment.
- See \fBNative Language System support\fR.
- .TP 8
- .B LC_CTYPE
- If set, only ctype character handling is changed.
- See \fBNative Language System support\fR.
- .TP 8
- .B LINES
- The number of lines in the terminal. See \fBTerminal management\fR.
- .TP 8
- .B LS_COLORS
- The format of this variable is reminiscent of the \fBtermcap(5)\fR
- file format; a colon-separated list of expressions of the form
- "\fIxx=string\fR", where "\fIxx\fR" is a two-character variable name. The
- variables with their associated defaults are:
- .PP
- .RS +8
- .RS +4
- .PD 0
- .TP 12
- no 0
- Normal (non-filename) text
- .TP 12
- fi 0
- Regular file
- .TP 12
- di 01;34
- Directory
- .TP 12
- ln 01;36
- Symbolic link
- .TP 12
- pi 33
- Named pipe (FIFO)
- .TP 12
- so 01;35
- Socket
- .TP 12
- do 01;35
- Door
- .TP 12
- bd 01;33
- Block device
- .TP 12
- cd 01;32
- Character device
- .TP 12
- ex 01;32
- Executable file
- .TP 12
- mi (none)
- Missing file (defaults to fi)
- .TP 12
- or (none)
- Orphaned symbolic link (defaults to ln)
- .TP 12
- lc ^[[
- Left code
- .TP 12
- rc m
- Right code
- .TP 12
- ec (none)
- End code (replaces lc+no+rc)
- .PD
- .RE
- .PP
- You need to include only the variables you want to change from
- the default.
- .PP
- File names can also be colorized based on filename extension.
- This is specified in the \fBLS_COLORS\fR variable using the syntax
- \fB"*ext=string"\fR. For example, using ISO 6429 codes, to color
- all C\-language source files blue you would specify \fB"*.c=34"\fR.
- This would color all files ending in \fB.c\fR in blue (34) color.
- .PP
- Control characters can be written either in C\-style\-escaped
- notation, or in stty\-like ^\-notation. The C\-style notation
- adds \fB^[\fR for Escape, \fB\_\fR for a normal space character,
- and \fB?\fR for Delete. In addition, the \fB^[\fR escape character
- can be used to override the default interpretation of \fB^[\fR,
- \fB^\fR, \fB:\fR and \fB=\fR.
- .PP
- Each file will be written as \fB<lc>\fR \fB<color-code>\fR
- \fB<rc>\fR \fB<filename>\fR \fB<ec>\fR. If the \fB<ec>\fR
- code is undefined, the sequence \fB<lc>\fR \fB<no>
- \fB<rc>\fR will be used instead. This is generally more convenient
- to use, but less general. The left, right and end codes are
- provided so you don't have to type common parts over and over
- again and to support weird terminals; you will generally not
- need to change them at all unless your terminal does not use
- ISO 6429 color sequences but a different system.
- .PP
- If your terminal does use ISO 6429 color codes, you can
- compose the type codes (i.e., all except the \fBlc\fR, \fBrc\fR,
- and \fBec\fR codes) from numerical commands separated by semicolons. The
- most common commands are:
- .PP
- .RS +8
- .PD 0
- .TP 4
- 0
- to restore default color
- .TP 4
- 1
- for brighter colors
- .TP 4
- 4
- for underlined text
- .TP 4
- 5
- for flashing text
- .TP 4
- 30
- for black foreground
- .TP 4
- 31
- for red foreground
- .TP 4
- 32
- for green foreground
- .TP 4
- 33
- for yellow (or brown) foreground
- .TP 4
- 34
- for blue foreground
- .TP 4
- 35
- for purple foreground
- .TP 4
- 36
- for cyan foreground
- .TP 4
- 37
- for white (or gray) foreground
- .TP 4
- 40
- for black background
- .TP 4
- 41
- for red background
- .TP 4
- 42
- for green background
- .TP 4
- 43
- for yellow (or brown) background
- .TP 4
- 44
- for blue background
- .TP 4
- 45
- for purple background
- .TP 4
- 46
- for cyan background
- .TP 4
- 47
- for white (or gray) background
- .PD
- .RE
- .PP
- Not all commands will work on all systems or display devices.
- .PP
- A few terminal programs do not recognize the default end code
- properly. If all text gets colorized after you do a directory
- listing, try changing the \fBno\fR and \fBfi\fR codes from 0 to the
- numerical codes for your standard fore- and background colors.
- .RE
- .TP 8
- .B MACHTYPE \fR(+)
- The machine type (microprocessor class or machine model), as determined at compile time.
- .TP 8
- .B NOREBIND \fR(+)
- If set, printable characters are not rebound to \fIself-insert-command\fR.
- See \fBNative Language System support\fR.
- .TP 8
- .B OSTYPE \fR(+)
- The operating system, as determined at compile time.
- .TP 8
- .B PATH
- A colon-separated list of directories in which to look for executables.
- Equivalent to the \fBpath\fR shell variable, but in a different format.
- .TP 8
- .B PWD \fR(+)
- Equivalent to the \fBcwd\fR shell variable, but not synchronized to it;
- updated only after an actual directory change.
- .TP 8
- .B REMOTEHOST \fR(+)
- The host from which the user has logged in remotely, if this is the case and
- the shell is able to determine it. Set only if the shell was so compiled;
- see the \fBversion\fR shell variable.
- .TP 8
- .B SHLVL \fR(+)
- Equivalent to the \fBshlvl\fR shell variable.
- .TP 8
- .B SYSTYPE \fR(+)
- The current system type. (Domain/OS only)
- .TP 8
- .B TERM
- Equivalent to the \fBterm\fR shell variable.
- .TP 8
- .B TERMCAP
- The terminal capability string. See \fBTerminal management\fR.
- .TP 8
- .B USER
- Equivalent to the \fBuser\fR shell variable.
- .TP 8
- .B VENDOR \fR(+)
- The vendor, as determined at compile time.
- .TP 8
- .B VISUAL
- The pathname to a default full-screen editor.
- See also the \fBEDITOR\fR environment variable
- and the \fIrun-fg-editor\fR editor command.
- .SH FILES
- .PD 0
- .TP 16
- .I /etc/csh.cshrc
- Read first by every shell.
- ConvexOS, Stellix and Intel use \fI/etc/cshrc\fR and
- NeXTs use \fI/etc/cshrc.std\fR.
- A/UX, AMIX, Cray and IRIX have no equivalent in \fIcsh\fR(1),
- but read this file in \fItcsh\fR anyway.
- Solaris 2.x does not have it either, but \fItcsh\fR reads \fI/etc/.cshrc\fR. (+)
- .TP 16
- .I /etc/csh.login
- Read by login shells after \fI/etc/csh.cshrc\fR.
- ConvexOS, Stellix and Intel use \fI/etc/login\fR,
- NeXTs use \fI/etc/login.std\fR, Solaris 2.x uses \fI/etc/.login\fR and
- A/UX, AMIX, Cray and IRIX use \fI/etc/cshrc\fR.
- .TP 16
- .I ~/.tcshrc \fR(+)
- Read by every shell after \fI/etc/csh.cshrc\fR or its equivalent.
- .TP 16
- .I ~/.cshrc
- Read by every shell, if \fI~/.tcshrc\fR doesn't exist,
- after \fI/etc/csh.cshrc\fR or its equivalent.
- This manual uses `\fI~/.tcshrc\fR' to mean `\fI~/.tcshrc\fR or,
- if \fI~/.tcshrc\fR is not found, \fI~/.cshrc\fR'.
- .TP 16
- .I ~/.history
- Read by login shells after \fI~/.tcshrc\fR
- if \fBsavehist\fR is set, but see also \fBhistfile\fR.
- .TP 16
- .I ~/.login
- Read by login shells after \fI~/.tcshrc\fR or \fI~/.history\fR.
- The shell may be compiled to read \fI~/.login\fR before instead of after
- \fI~/.tcshrc\fR and \fI~/.history\fR; see the \fBversion\fR shell variable.
- .TP 16
- .I ~/.cshdirs \fR(+)
- Read by login shells after \fI~/.login\fR
- if \fBsavedirs\fR is set, but see also \fBdirsfile\fR.
- .TP 16
- .I /etc/csh.logout
- Read by login shells at logout.
- ConvexOS, Stellix and Intel use \fI/etc/logout\fR and
- NeXTs use \fI/etc/logout.std\fR.
- A/UX, AMIX, Cray and IRIX have no equivalent in \fIcsh\fR(1),
- but read this file in \fItcsh\fR anyway.
- Solaris 2.x does not have it either, but \fItcsh\fR reads \fI/etc/.logout\fR. (+)
- .TP 16
- .I ~/.logout
- Read by login shells at logout after \fI/etc/csh.logout\fR or its equivalent.
- .TP 16
- .I /bin/sh
- Used to interpret shell scripts not starting with a `#'.
- .TP 16
- .I /tmp/sh*
- Temporary file for `<<'.
- .TP 16
- .I /etc/passwd
- Source of home directories for `~name' substitutions.
- .PD
- .PP
- The order in which startup files are read may differ if the shell was so
- compiled; see \fBStartup and shutdown\fR and the \fBversion\fR shell variable.
- .SH "NEW FEATURES (+)"
- This manual describes \fItcsh\fR as a single entity,
- but experienced \fIcsh\fR(1) users will want to pay special attention to
- \fItcsh\fR's new features.
- .PP
- A command-line editor, which supports GNU Emacs or \fIvi\fR(1)-style
- key bindings. See \fBThe command-line editor\fR and \fBEditor commands\fR.
- .PP
- Programmable, interactive word completion and listing.
- See \fBCompletion and listing\fR and the \fIcomplete\fR and \fIuncomplete\fR
- builtin commands.
- .PP
- \fBSpelling correction\fR (q.v.) of filenames, commands and variables.
- .PP
- \fBEditor commands\fR (q.v.) which perform other useful functions in the middle of
- typed commands, including documentation lookup (\fIrun-help\fR),
- quick editor restarting (\fIrun-fg-editor\fR) and
- command resolution (\fIwhich-command\fR).
- .PP
- An enhanced history mechanism. Events in the history list are time-stamped.
- See also the \fIhistory\fR command and its associated shell variables,
- the previously undocumented `#' event specifier and new modifiers
- under \fBHistory substitution\fR,
- the \fI*-history\fR, \fIhistory-search-*\fR, \fIi-search-*\fR, \fIvi-search-*\fR and
- \fItoggle-literal-history\fR editor commands
- and the \fBhistlit\fR shell variable.
- .PP
- Enhanced directory parsing and directory stack handling.
- See the \fIcd\fR, \fIpushd\fR, \fIpopd\fR and \fIdirs\fR commands and their associated
- shell variables, the description of \fBDirectory stack substitution\fR,
- the \fBdirstack\fR, \fBowd\fR and \fBsymlinks\fR shell variables and
- the \fInormalize-command\fR and \fInormalize-path\fR editor commands.
- .PP
- Negation in glob-patterns. See \fBFilename substitution\fR.
- .PP
- New \fBFile inquiry operators\fR (q.v.) and a \fIfiletest\fR
- builtin which uses them.
- .PP
- A variety of \fBAutomatic, periodic and timed events\fR (q.v.) including
- scheduled events, special aliases, automatic logout and terminal locking,
- command timing and watching for logins and logouts.
- .PP
- Support for the Native Language System
- (see \fBNative Language System support\fR),
- OS variant features
- (see \fBOS variant support\fR and the \fBecho_style\fR shell variable)
- and system-dependent file locations (see \fBFILES\fR).
- .PP
- Extensive terminal-management capabilities. See \fBTerminal management\fR.
- .PP
- New builtin commands including \fIbuiltins\fR, \fIhup\fR, \fIls\-F\fR,
- \fInewgrp\fR, \fIprintenv\fR, \fIwhich\fR and \fIwhere\fR (q.v.).
- .PP
- New variables that make useful information easily available to the shell.
- See the \fBgid\fR, \fBloginsh\fR, \fBoid\fR, \fBshlvl\fR, \fBtcsh\fR,
- \fBtty\fR, \fBuid\fR and \fBversion\fR shell variables and the \fBHOST\fR,
- \fBREMOTEHOST\fR, \fBVENDOR\fR, \fBOSTYPE\fR and \fBMACHTYPE\fR environment
- variables.
- .PP
- A new syntax for including useful information in the prompt string
- (see \fBprompt\fR),
- and special prompts for loops and spelling correction
- (see \fBprompt2\fR and \fBprompt3\fR).
- .PP
- Read-only variables. See \fBVariable substitution\fR.
- .SH BUGS
- When a suspended command is restarted, the shell prints the directory
- it started in if this is different from the current directory. This can
- be misleading (i.e., wrong) as the job may have changed directories internally.
- .PP
- Shell builtin functions are not stoppable/restartable. Command sequences
- of the form `a ; b ; c' are also not handled gracefully when stopping is
- attempted. If you suspend `b', the shell will then immediately execute
- `c'. This is especially noticeable if this expansion results from an
- \fIalias\fR. It suffices to place the sequence of commands in ()'s to force it
- to a subshell, i.e., `( a ; b ; c )'.
- .PP
- Control over tty output after processes are started is primitive; perhaps
- this will inspire someone to work on a good virtual terminal interface.
- In a virtual terminal interface much more interesting things could be
- done with output control.
- .PP
- Alias substitution is most often used to clumsily simulate shell procedures;
- shell procedures should be provided rather than aliases.
- .PP
- Control structures should be parsed rather than being recognized as
- built-in commands. This would allow control commands to be placed anywhere,
- to be combined with `|', and to be used with `&' and `;' metasyntax.
- .PP
- \fIforeach\fR doesn't ignore here documents when looking for its \fIend\fR.
- .PP
- It should be possible to use the `:' modifiers on the output of command
- substitutions.
- .PP
- The screen update for lines longer than the screen width is very poor
- if the terminal cannot move the cursor up (i.e., terminal type `dumb').
- .PP
- \fBHPATH\fR and \fBNOREBIND\fR don't need to be environment variables.
- .PP
- Glob-patterns which do not use `?', `*' or `[]' or which use `{}' or `~'
- are not negated correctly.
- .PP
- The single-command form of \fIif\fR does output redirection even if
- the expression is false and the command is not executed.
- .PP
- \fIls\-F\fR includes file identification characters when sorting filenames
- and does not handle control characters in filenames well. It cannot be
- interrupted.
- .PP
- Command substitution supports multiple commands and conditions, but not
- cycles or backward \fIgoto\fRs.
- .PP
- Report bugs at http://bugs.gw.com/, preferably with fixes. If you want to
- help maintain and test tcsh, send mail to tcsh-request@mx.gw.com with the
- text `subscribe tcsh' on a line by itself in the body.
- .SH THE T IN TCSH
- In 1964, DEC produced the PDP-6. The PDP-10 was a later re-implementation. It
- was re-christened the DECsystem-10 in 1970 or so when DEC brought out the
- second model, the KI10.
- .PP
- TENEX was created at Bolt, Beranek & Newman (a Cambridge, Massachusetts
- think tank) in
- 1972 as an experiment in demand-paged virtual memory operating systems. They
- built a new pager for the DEC PDP-10 and created the OS to go with it. It was
- extremely successful in academia.
- .PP
- In 1975, DEC brought out a new model of the PDP-10, the KL10; they intended to
- have only a version of TENEX, which they had licensed from BBN, for the new
- box. They called their version TOPS-20 (their capitalization is trademarked).
- A lot of TOPS-10 users (`The OPerating System for PDP-10') objected; thus DEC
- found themselves supporting two incompatible systems on the same hardware--but
- then there were 6 on the PDP-11!
- .PP
- TENEX, and TOPS-20 to version 3, had command completion
- via a user-code-level subroutine library called ULTCMD. With version 3, DEC
- moved all that capability and more into the monitor (`kernel' for you Unix
- types), accessed by the COMND% JSYS (`Jump to SYStem' instruction, the
- supervisor call mechanism [are my IBM roots also showing?]).
- .PP
- The creator of tcsh was impressed by this feature and several others of TENEX
- and TOPS-20, and created a version of csh which mimicked them.
- .SH LIMITATIONS
- The system limits argument lists to ARG_MAX characters.
- .PP
- The number of arguments to a command which involves filename expansion is
- limited to 1/6th the number of characters allowed in an argument list.
- .PP
- Command substitutions may substitute no more characters than are allowed in
- an argument list.
- .PP
- To detect looping, the shell restricts the number of \fIalias\fR
- substitutions on a single line to 20.
- .SH "SEE ALSO"
- csh(1), emacs(1), ls(1), newgrp(1), sh(1), setpath(1), stty(1), su(1),
- tset(1), vi(1), x(1), access(2), execve(2), fork(2), killpg(2),
- pipe(2), setrlimit(2), sigvec(2), stat(2), umask(2), vfork(2), wait(2),
- malloc(3), setlocale(3), tty(4), a.out(5), termcap(5), environ(7),
- termio(7), Introduction to the C Shell
- .SH VERSION
- This manual documents tcsh 6.18.01 (Astron) 2012-02-14.
- .SH AUTHORS
- .PD 0
- .TP 2
- William Joy
- Original author of \fIcsh\fR(1)
- .TP 2
- J.E. Kulp, IIASA, Laxenburg, Austria
- Job control and directory stack features
- .TP 2
- Ken Greer, HP Labs, 1981
- File name completion
- .TP 2
- Mike Ellis, Fairchild, 1983
- Command name recognition/completion
- .TP 2
- Paul Placeway, Ohio State CIS Dept., 1983-1993
- Command line editor, prompt routines, new glob syntax and numerous fixes
- and speedups
- .TP 2
- Karl Kleinpaste, CCI 1983-4
- Special aliases, directory stack extraction stuff, login/logout watch,
- scheduled events, and the idea of the new prompt format
- .TP 2
- Rayan Zachariassen, University of Toronto, 1984
- \fIls\-F\fR and \fIwhich\fR builtins and numerous bug fixes, modifications
- and speedups
- .TP 2
- Chris Kingsley, Caltech
- Fast storage allocator routines
- .TP 2
- Chris Grevstad, TRW, 1987
- Incorporated 4.3BSD \fIcsh\fR into \fItcsh\fR
- .TP 2
- Christos S. Zoulas, Cornell U. EE Dept., 1987-94
- Ports to HPUX, SVR2 and SVR3, a SysV version of getwd.c, SHORT_STRINGS support
- and a new version of sh.glob.c
- .TP 2
- James J Dempsey, BBN, and Paul Placeway, OSU, 1988
- A/UX port
- .TP 2
- Daniel Long, NNSC, 1988
- \fBwordchars\fR
- .TP 2
- Patrick Wolfe, Kuck and Associates, Inc., 1988
- \fIvi\fR mode cleanup
- .TP 2
- David C Lawrence, Rensselaer Polytechnic Institute, 1989
- \fBautolist\fR and ambiguous completion listing
- .TP 2
- Alec Wolman, DEC, 1989
- Newlines in the prompt
- .TP 2
- Matt Landau, BBN, 1989
- \fI~/.tcshrc\fR
- .TP 2
- Ray Moody, Purdue Physics, 1989
- Magic space bar history expansion
- .TP 2
- Mordechai ????, Intel, 1989
- printprompt() fixes and additions
- .TP 2
- Kazuhiro Honda, Dept. of Computer Science, Keio University, 1989
- Automatic spelling correction and \fBprompt3\fR
- .TP 2
- Per Hedeland, Ellemtel, Sweden, 1990-
- Various bugfixes, improvements and manual updates
- .TP 2
- Hans J. Albertsson (Sun Sweden)
- \fBampm\fR, \fIsettc\fR and \fItelltc\fR
- .TP 2
- Michael Bloom
- Interrupt handling fixes
- .TP 2
- Michael Fine, Digital Equipment Corp
- Extended key support
- .TP 2
- Eric Schnoebelen, Convex, 1990
- Convex support, lots of \fIcsh\fR bug fixes,
- save and restore of directory stack
- .TP 2
- Ron Flax, Apple, 1990
- A/UX 2.0 (re)port
- .TP 2
- Dan Oscarsson, LTH Sweden, 1990
- NLS support and simulated NLS support for non NLS sites, fixes
- .TP 2
- Johan Widen, SICS Sweden, 1990
- \fBshlvl\fR, Mach support, \fIcorrect-line\fR, 8-bit printing
- .TP 2
- Matt Day, Sanyo Icon, 1990
- POSIX termio support, SysV limit fixes
- .TP 2
- Jaap Vermeulen, Sequent, 1990-91
- Vi mode fixes, expand-line, window change fixes, Symmetry port
- .TP 2
- Martin Boyer, Institut de recherche d'Hydro-Quebec, 1991
- \fBautolist\fR beeping options, modified the history search to search for
- the whole string from the beginning of the line to the cursor.
- .TP 2
- Scott Krotz, Motorola, 1991
- Minix port
- .TP 2
- David Dawes, Sydney U. Australia, Physics Dept., 1991
- SVR4 job control fixes
- .TP 2
- Jose Sousa, Interactive Systems Corp., 1991
- Extended \fIvi\fR fixes and \fIvi\fR delete command
- .TP 2
- Marc Horowitz, MIT, 1991
- ANSIfication fixes, new exec hashing code, imake fixes, \fIwhere\fR
- .TP 2
- Bruce Sterling Woodcock, sterling@netcom.com, 1991-1995
- ETA and Pyramid port, Makefile and lint fixes, \fBignoreeof\fR=n addition, and
- various other portability changes and bug fixes
- .TP 2
- Jeff Fink, 1992
- \fIcomplete-word-fwd\fR and \fIcomplete-word-back\fR
- .TP 2
- Harry C. Pulley, 1992
- Coherent port
- .TP 2
- Andy Phillips, Mullard Space Science Lab U.K., 1992
- VMS-POSIX port
- .TP 2
- Beto Appleton, IBM Corp., 1992
- Walking process group fixes, \fIcsh\fR bug fixes,
- POSIX file tests, POSIX SIGHUP
- .TP 2
- Scott Bolte, Cray Computer Corp., 1992
- CSOS port
- .TP 2
- Kaveh R. Ghazi, Rutgers University, 1992
- Tek, m88k, Titan and Masscomp ports and fixes. Added autoconf support.
- .TP 2
- Mark Linderman, Cornell University, 1992
- OS/2 port
- .TP 2
- Mika Liljeberg, liljeber@kruuna.Helsinki.FI, 1992
- Linux port
- .TP 2
- Tim P. Starrin, NASA Langley Research Center Operations, 1993
- Read-only variables
- .TP 2
- Dave Schweisguth, Yale University, 1993-4
- New man page and tcsh.man2html
- .TP 2
- Larry Schwimmer, Stanford University, 1993
- AFS and HESIOD patches
- .TP 2
- Luke Mewburn, RMIT University, 1994-6
- Enhanced directory printing in prompt,
- added \fBellipsis\fR and \fBrprompt\fR.
- .TP 2
- Edward Hutchins, Silicon Graphics Inc., 1996
- Added implicit cd.
- .TP 2
- Martin Kraemer, 1997
- Ported to Siemens Nixdorf EBCDIC machine
- .TP 2
- Amol Deshpande, Microsoft, 1997
- Ported to WIN32 (Windows/95 and Windows/NT); wrote all the missing library
- and message catalog code to interface to Windows.
- .TP 2
- Taga Nayuta, 1998
- Color ls additions.
- .PD
- .PP
- .SH "THANKS TO"
- Bryan Dunlap, Clayton Elwell, Karl Kleinpaste, Bob Manson, Steve Romig,
- Diana Smetters, Bob Sutterfield, Mark Verber, Elizabeth Zwicky and all
- the other people at Ohio State for suggestions and encouragement
- .PP
- All the people on the net, for putting up with,
- reporting bugs in, and suggesting new additions to each and every version
- .PP
- Richard M. Alderson III, for writing the `T in tcsh' section