source: trunk/third/tcsh/tcsh.man @ 22039

Revision 22039, 191.4 KB checked in by ghudson, 20 years ago (diff)
Merge with tcsh 6.14.00.
Line 
1.\" Copyright (c) 1980, 1990, 1993
2.\"     The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\" Style notes for the tcsh man page:
29.\"
30.\" - Tags in lists are bold, except in the FILES section where they are
31.\"   italic.
32.\"
33.\" - References are bold for section headings and environment and shell
34.\"   variables and italic for commands (externals, builtins, aliases, and
35.\"   editor commands) and arguments to commands.
36.\"
37.\" - Be careful with the .B and .I macros: they handle only a limited number
38.\"   of words. Work around this with \fB and \fI, but only if absolutely
39.\"   necessary, because tcsh.man2html uses .B/.I to find name anchors.
40.\"
41.\" - Indent in multiples of 4, usually 8.
42.\"
43.\" - Use `', not '' or "", except of course in shell syntax examples.
44.\"   '' at the beginning of a line will vanish!
45.\"
46.\" - Use \-, not -.
47.\"
48.\" - Include the tilde when naming dot files. `~/.login', not `.login'.
49.\"
50.\" - Refer to external commands in man page format, e.g., `csh(1)'. However,
51.\"   tcsh is `tcsh', not `tcsh(1)', because this is the tcsh man page (and
52.\"   see the next note anyway).
53.\"
54.\" - Say `the shell', not `tcsh', unless distinguishing between tcsh and csh.
55.\"
56.\" - Say `shell variable'/`environment variable' instead of `variable'
57.\"   and `builtin command'/`editor command' instead of `builtin' or `command'
58.\"   unless the distinction is absolutely clear from context.
59.\"
60.\" - Use the simple present tense. `The shell uses', not `The shell will use'.
61.\"
62.\" - IMPORTANT: Cross-reference as much as possible. Commands, variables,
63.\"   etc. in the reference section should be mentioned in the appropriate
64.\"   descriptive section, or at least in the reference-section description
65.\"   of another command (or whatever) which is mentioned in a description
66.\"   section. Remember to note OS-specific things in "OS variant support",
67.\"   new features in NEW FEATURES and referenced external commands in SEE
68.\"   ALSO.
69.\"
70.\" - tcsh.man2html depends heavily on the specific nroff commands used in the
71.\"   man page when the script was written. Please stick closely to the style
72.\"   used here if you can. In particular, please don't use nroff commands
73.\"   which aren't already used herein.
74.\"
75.TH TCSH 1 "25 March 2005" "Astron 6.14.00"
76.SH NAME
77tcsh \- C shell with file name completion and command line editing
78.SH SYNOPSIS
79.B tcsh \fR[\fB\-bcdefFimnqstvVxX\fR] [\fB\-Dname\fR[\fB=value\fR]] [arg ...]
80.br
81.B tcsh \-l
82.SH DESCRIPTION
83\fItcsh\fR is an enhanced but completely compatible version of the Berkeley
84UNIX C shell, \fIcsh\fR(1).
85It is a command language interpreter usable both as an interactive login
86shell and a shell script command processor.
87It includes a command-line editor (see \fBThe command-line editor\fR),
88programmable word completion (see \fBCompletion and listing\fR),
89spelling correction (see \fBSpelling correction\fR),
90a history mechanism (see \fBHistory substitution\fR),
91job control (see \fBJobs\fR)
92and a C-like syntax.
93The \fBNEW FEATURES\fR section describes major enhancements of \fItcsh\fR
94over \fIcsh\fR(1).
95Throughout this manual, features of
96\fItcsh\fR not found in most \fIcsh\fR(1) implementations
97(specifically, the 4.4BSD \fIcsh\fR)
98are labeled with `(+)', and features which are present in \fIcsh\fR(1)
99but not usually documented are labeled with `(u)'.
100.SS "Argument list processing"
101If the first argument (argument 0) to the shell is `\-' then it is a
102login shell.  A login shell can be also specified by invoking the shell with
103the \fB\-l\fR flag as the only argument.
104.PP
105The rest of the flag arguments are interpreted as follows:
106.TP 4
107.B \-b
108Forces a ``break'' from option processing, causing any
109further shell arguments to be treated as non-option arguments.  The remaining
110arguments will not be interpreted as shell options.  This may be used to pass
111options to a shell script without confusion or possible subterfuge.  The shell
112will not run a set-user ID script without this option.
113.TP 4
114.B \-c
115Commands are read from the following argument (which must be present, and
116must be a single argument),
117stored in the \fBcommand\fR shell variable for reference, and executed.
118Any remaining arguments are placed in the \fBargv\fR shell variable.
119.TP 4
120.B \-d
121The shell loads the directory stack from \fI~/.cshdirs\fR as described under
122\fBStartup and shutdown\fR, whether or not it is a login shell. (+)
123.TP 4
124.B \-D\fIname\fR[=\fIvalue\fR]
125Sets the environment variable \fIname\fR to \fIvalue\fR. (Domain/OS only) (+)
126.TP 4
127.B \-e
128The shell exits if any invoked command terminates abnormally or
129yields a non-zero exit status.
130.TP 4
131.B \-f
132The shell ignores \fI~/.tcshrc\fR, and thus starts faster.
133.TP 4
134.B \-F
135The shell uses \fIfork\fR(2) instead of \fIvfork\fR(2) to spawn processes. (Convex/OS only) (+)
136.TP 4
137.B \-i
138The shell is interactive and prompts for its top-level input, even if
139it appears to not be a terminal.  Shells are interactive without this option if
140their inputs and outputs are terminals.
141.TP 4
142.B \-l
143The shell is a login shell.  Applicable only if \fB\-l\fR is the only
144flag specified.
145.TP 4
146.B \-m
147The shell loads \fI~/.tcshrc\fR even if it does not belong to the effective
148user.  Newer versions of \fIsu\fR(1) can pass \fB\-m\fR to the shell. (+)
149.TP 4
150.B \-n
151The shell parses commands but does not execute them.
152This aids in debugging shell scripts.
153.TP 4
154.B \-q
155The shell accepts SIGQUIT (see \fBSignal handling\fR) and behaves when
156it is used under a debugger.  Job control is disabled. (u)
157.TP 4
158.B \-s
159Command input is taken from the standard input.
160.TP 4
161.B \-t
162The shell reads and executes a single line of input.  A `\\' may be used to
163escape the newline at the end of this line and continue onto another line.
164.TP 4
165.B \-v
166Sets the \fBverbose\fR shell variable, so that
167command input is echoed after history substitution.
168.TP 4
169.B \-x
170Sets the \fBecho\fR shell variable, so that commands are echoed
171immediately before execution.
172.TP 4
173.B \-V
174Sets the \fBverbose\fR shell variable even before executing \fI~/.tcshrc\fR.
175.TP 4
176.B \-X
177Is to \fB\-x\fR as \fB\-V\fR is to \fB\-v\fR.
178.TP 4
179.B \-\-help
180Print a help message on the standard output and exit. (+)
181.TP 4
182.B \-\-version
183Print the version/platform/compilation options on the standard output and exit.
184This information is also contained in the \fBversion\fR shell variable. (+)
185.PP
186After processing of flag arguments, if arguments remain but none of the
187\fB\-c\fR, \fB\-i\fR, \fB\-s\fR, or \fB\-t\fR options were given, the first
188argument is taken as the name of a file of commands, or ``script'', to
189be executed.  The shell opens this file and saves its name for possible
190resubstitution by `$0'.  Because many systems use either the standard
191version 6 or version 7 shells whose shell scripts are not compatible
192with this shell, the shell uses such a `standard' shell to execute a script
193whose first character is not a `#', i.e., that does not start with a
194comment.
195.PP
196Remaining arguments are placed in the \fBargv\fR shell variable.
197.SS "Startup and shutdown"
198A login shell begins by executing commands from the system files
199\fI/etc/csh.cshrc\fR and \fI/etc/csh.login\fR.
200It then executes commands from files in the user's \fBhome\fR directory:
201first \fI~/.tcshrc\fR (+)
202or, if \fI~/.tcshrc\fR is not found, \fI~/.cshrc\fR,
203then \fI~/.history\fR (or the value of the \fBhistfile\fR shell variable),
204then \fI~/.login\fR,
205and finally \fI~/.cshdirs\fR (or the value of the \fBdirsfile\fR shell variable) (+).
206The shell may read \fI/etc/csh.login\fR before instead of after
207\fI/etc/csh.cshrc\fR, and \fI~/.login\fR before instead of after
208\fI~/.tcshrc\fR or \fI~/.cshrc\fR and \fI~/.history\fR, if so compiled;
209see the \fBversion\fR shell variable. (+)
210.PP
211Non-login shells read only \fI/etc/csh.cshrc\fR and \fI~/.tcshrc\fR
212or \fI~/.cshrc\fR on startup.
213.PP
214For examples of startup files, please consult
215\fIhttp://tcshrc.sourceforge.net\fR.
216.PP
217Commands like \fIstty\fR(1) and \fItset\fR(1),
218which need be run only once per login, usually go in one's \fI~/.login\fR file.
219Users who need to use the same set of files with both \fIcsh\fR(1) and
220\fItcsh\fR can have only a \fI~/.cshrc\fR which checks for the existence of the
221\fBtcsh\fR shell variable (q.v.) before using \fItcsh\fR-specific commands,
222or can have both a \fI~/.cshrc\fR and a \fI~/.tcshrc\fR which \fIsource\fRs
223(see the builtin command) \fI~/.cshrc\fR.
224The rest of this manual uses `\fI~/.tcshrc\fR' to mean `\fI~/.tcshrc\fR or,
225if \fI~/.tcshrc\fR is not found, \fI~/.cshrc\fR'.
226.PP
227In the normal case, the shell begins reading commands from the terminal,
228prompting with `> '.  (Processing of arguments and the use of the shell to
229process files containing command scripts are described later.)
230The shell repeatedly reads a line of command input, breaks it into words,
231places it on the command history list, parses it and executes each command
232in the line.
233.PP
234One can log out by typing `^D' on an empty line, `logout' or `login' or
235via the shell's autologout mechanism (see the \fBautologout\fR shell variable).
236When a login shell terminates it sets the \fBlogout\fR shell variable to
237`normal' or `automatic' as appropriate, then
238executes commands from the files
239\fI/etc/csh.logout\fR and \fI~/.logout\fR.  The shell may drop DTR on logout
240if so compiled; see the \fBversion\fR shell variable.
241.PP
242The names of the system login and logout files vary from system to system for
243compatibility with different \fIcsh\fR(1) variants; see \fBFILES\fR.
244.SS Editing
245We first describe \fBThe command-line editor\fR.
246The \fBCompletion and listing\fR and \fBSpelling correction\fR sections
247describe two sets of functionality that are implemented as editor commands
248but which deserve their own treatment.
249Finally, \fBEditor commands\fR lists and describes
250the editor commands specific to the shell and their default bindings.
251.SS "The command-line editor (+)"
252Command-line input can be edited using key sequences much like those used in
253GNU Emacs or \fIvi\fR(1).
254The editor is active only when the \fBedit\fR shell variable is set, which
255it is by default in interactive shells.
256The \fIbindkey\fR builtin can display and change key bindings.
257Emacs-style key bindings are used by default
258(unless the shell was compiled otherwise; see the \fBversion\fR shell variable),
259but \fIbindkey\fR can change the key bindings to \fIvi\fR-style bindings en masse.
260.PP
261The shell always binds the arrow keys (as defined in the \fBTERMCAP\fR
262environment variable) to
263.PP
264.PD 0
265.RS +4
266.TP 8
267down
268\fIdown-history\fR
269.TP 8
270up
271\fIup-history\fR
272.TP 8
273left
274\fIbackward-char\fR
275.TP 8
276right
277\fIforward-char\fR
278.PD
279.RE
280.PP
281unless doing so would alter another single-character binding.
282One can set the arrow key escape sequences to the empty string with \fIsettc\fR
283to prevent these bindings.
284The ANSI/VT100 sequences for arrow keys are always bound.
285.PP
286Other key bindings are, for the most part, what Emacs and \fIvi\fR(1)
287users would expect and can easily be displayed by \fIbindkey\fR, so there
288is no need to list them here.  Likewise, \fIbindkey\fR can list the editor
289commands with a short description of each.
290.PP
291Note that editor commands do not have the same notion of a ``word'' as does the
292shell.  The editor delimits words with any non-alphanumeric characters not in
293the shell variable \fBwordchars\fR, while the shell recognizes only whitespace
294and some of the characters with special meanings to it, listed under
295\fBLexical structure\fR.
296.SS "Completion and listing (+)"
297The shell is often able to complete words when given a unique abbreviation.
298Type part of a word (for example `ls /usr/lost') and hit the tab key to
299run the \fIcomplete-word\fR editor command.
300The shell completes the filename `/usr/lost' to `/usr/lost+found/',
301replacing the incomplete word with the complete word in the input buffer.
302(Note the terminal `/'; completion adds a `/' to the
303end of completed directories and a space to the end of other completed words,
304to speed typing and provide a visual indicator of successful completion.
305The \fBaddsuffix\fR shell variable can be unset to prevent this.)
306If no match is found (perhaps `/usr/lost+found' doesn't exist),
307the terminal bell rings.
308If the word is already complete (perhaps there is a `/usr/lost' on your
309system, or perhaps you were thinking too far ahead and typed the whole thing)
310a `/' or space is added to the end if it isn't already there.
311.PP
312Completion works anywhere in the line, not at just the end; completed
313text pushes the rest of the line to the right.  Completion in the middle of a word
314often results in leftover characters to the right of the cursor that need
315to be deleted.
316.PP
317Commands and variables can be completed in much the same way.
318For example, typing `em[tab]' would complete `em' to
319`emacs' if \fIemacs\fR were the only command on your system beginning with `em'.
320Completion can find a command in any directory in \fBpath\fR or if
321given a full pathname.
322Typing `echo $ar[tab]' would complete `$ar' to `$argv'
323if no other variable began with `ar'.
324.PP
325The shell parses the input buffer to determine whether the word you want to
326complete should be completed as a filename, command or variable.
327The first word in the buffer and the first word following
328`;', `|', `|&', `&&' or `||' is considered to be a command.
329A word beginning with `$' is considered to be a variable.
330Anything else is a filename.  An empty line is `completed' as a filename.
331.PP
332You can list the possible completions of a word at any time by typing `^D'
333to run the \fIdelete-char-or-list-or-eof\fR editor command.
334The shell lists the possible completions using the \fIls\-F\fR builtin (q.v.)
335and reprints the prompt and unfinished command line, for example:
336.IP "" 4
337> ls /usr/l[^D]
338.br
339lbin/       lib/        local/      lost+found/
340.br
341> ls /usr/l
342.PP
343If the \fBautolist\fR shell variable is set, the shell lists the remaining
344choices (if any) whenever completion fails:
345.IP "" 4
346> set autolist
347.br
348> nm /usr/lib/libt[tab]
349.br
350libtermcap.a@ libtermlib.a@
351.br
352> nm /usr/lib/libterm
353.PP
354If \fBautolist\fR is set to `ambiguous', choices are listed only when
355completion fails and adds no new characters to the word being completed.
356.PP
357A filename to be completed can contain variables, your own or others' home
358directories abbreviated with `~' (see \fBFilename substitution\fR) and
359directory stack entries abbreviated with `='
360(see \fBDirectory stack substitution\fR).  For example,
361.IP "" 4
362> ls ~k[^D]
363.br
364kahn    kas     kellogg
365.br
366> ls ~ke[tab]
367.br
368> ls ~kellogg/
369.PP
370or
371.IP "" 4
372> set local = /usr/local
373.br
374> ls $lo[tab]
375.br
376> ls $local/[^D]
377.br
378bin/ etc/ lib/ man/ src/
379.br
380> ls $local/
381.PP
382Note that variables can also be expanded explicitly with the
383\fIexpand-variables\fR editor command.
384.PP
385\fIdelete-char-or-list-or-eof\fR lists at only the end of the line;
386in the middle of a line it deletes the character under the cursor and
387on an empty line it logs one out or, if \fBignoreeof\fR is set, does nothing.
388`M-^D', bound to the editor command \fIlist-choices\fR, lists completion
389possibilities anywhere on a line, and \fIlist-choices\fR (or any one of the
390related editor commands that do or don't delete, list and/or log out,
391listed under \fIdelete-char-or-list-or-eof\fR) can be bound to `^D' with
392the \fIbindkey\fR builtin command if so desired.
393.PP
394The \fIcomplete-word-fwd\fR and \fIcomplete-word-back\fR editor commands
395(not bound to any keys by default) can be used to cycle up and down through
396the list of possible completions, replacing the current word with the next or
397previous word in the list.
398.PP
399The shell variable \fBfignore\fR can be set to a list of suffixes to be
400ignored by completion.  Consider the following:
401.IP "" 4
402> ls
403.br
404Makefile        condiments.h~   main.o          side.c
405.br
406README          main.c          meal            side.o
407.br
408condiments.h    main.c~
409.br
410> set fignore = (.o \\~)
411.br
412> emacs ma[^D]
413.br
414main.c   main.c~  main.o
415.br
416> emacs ma[tab]
417.br
418> emacs main.c
419.PP
420`main.c~' and `main.o' are ignored by completion (but not listing),
421because they end in suffixes in \fBfignore\fR.
422Note that a `\\' was needed in front of `~' to prevent it from being
423expanded to \fBhome\fR as described under \fBFilename substitution\fR.
424\fBfignore\fR is ignored if only one completion is possible.
425.PP
426If the \fBcomplete\fR shell variable is set to `enhance', completion
4271) ignores case and 2) considers periods, hyphens and underscores
428(`.', `\-' and `_') to be word separators and hyphens and underscores to
429be equivalent.  If you had the following files
430.IP "" 4
431comp.lang.c      comp.lang.perl   comp.std.c++
432.br
433comp.lang.c++    comp.std.c
434.PP
435and typed `mail \-f c.l.c[tab]', it would be completed to
436`mail \-f comp.lang.c', and ^D would list `comp.lang.c' and `comp.lang.c++'.
437`mail \-f c..c++[^D]' would list `comp.lang.c++' and `comp.std.c++'.  Typing
438`rm a\-\-file[^D]' in the following directory
439.IP "" 4
440A_silly_file    a-hyphenated-file    another_silly_file
441.PP
442would list all three files, because case is ignored and hyphens and
443underscores are equivalent.  Periods, however, are not equivalent to
444hyphens or underscores.
445.PP
446Completion and listing are affected by several other shell variables:
447\fBrecexact\fR can be set to complete on the shortest possible unique
448match, even if more typing might result in a longer match:
449.IP "" 4
450> ls
451.br
452fodder   foo      food     foonly
453.br
454> set recexact
455.br
456> rm fo[tab]
457.PP
458just beeps, because `fo' could expand to `fod' or `foo', but if we type
459another `o',
460.IP "" 4
461> rm foo[tab]
462.br
463> rm foo
464.PP
465the completion completes on `foo', even though `food' and `foonly'
466also match.
467\fBautoexpand\fR can be set to run the \fIexpand-history\fR editor command
468before each completion attempt, \fBautocorrect\fR can be set to
469spelling-correct the word to be completed (see \fBSpelling correction\fR)
470before each completion attempt and \fBcorrect\fR can be set to complete
471commands automatically after one hits `return'.
472\fBmatchbeep\fR can be set to make completion beep or not beep in a variety
473of situations, and \fBnobeep\fR can be set to never beep at all.
474\fBnostat\fR can be set to a list of directories and/or patterns that
475match directories to prevent the completion mechanism from \fIstat\fR(2)ing
476those directories.
477\fBlistmax\fR and \fBlistmaxrows\fR can be set to limit the number of items
478and rows (respectively) that are listed without asking first.
479\fBrecognize_only_executables\fR can be set to make the shell list only
480executables when listing commands, but it is quite slow.
481.PP
482Finally, the \fIcomplete\fR builtin command can be used to tell the shell how
483to complete words other than filenames, commands and variables.
484Completion and listing do not work on glob-patterns (see \fBFilename substitution\fR),
485but the \fIlist-glob\fR and \fIexpand-glob\fR editor commands perform
486equivalent functions for glob-patterns.
487.SS "Spelling correction (+)"
488The shell can sometimes correct the spelling of filenames, commands and variable names
489as well as completing and listing them.
490.PP
491Individual words can be spelling-corrected with the \fIspell-word\fR
492editor command (usually bound to M-s and M-S)
493and the entire input buffer with \fIspell-line\fR (usually bound to M-$).
494The \fBcorrect\fR shell variable can be set to `cmd' to correct the
495command name or `all' to correct the entire line each time return is typed,
496and \fBautocorrect\fR can be set to correct the word to be completed
497before each completion attempt.
498.PP
499When spelling correction is invoked in any of these ways and
500the shell thinks that any part of the command line is misspelled,
501it prompts with the corrected line:
502.IP "" 4
503> set correct = cmd
504.br
505> lz /usr/bin
506.br
507CORRECT>ls /usr/bin (y|n|e|a)?
508.PP
509One can answer `y' or space to execute the corrected line,
510`e' to leave the uncorrected command in the input buffer,
511`a' to abort the command as if `^C' had been hit, and
512anything else to execute the original line unchanged.
513.PP
514Spelling correction recognizes user-defined completions (see the
515\fIcomplete\fR builtin command).  If an input word in a position for
516which a completion is defined resembles a word in the completion list,
517spelling correction registers a misspelling and suggests the latter
518word as a correction.  However, if the input word does not match any of
519the possible completions for that position, spelling correction does
520not register a misspelling.
521.PP
522Like completion, spelling correction works anywhere in the line,
523pushing the rest of the line to the right and possibly leaving
524extra characters to the right of the cursor.
525.PP
526Beware: spelling correction is not guaranteed to work the way one intends,
527and is provided mostly as an experimental feature.
528Suggestions and improvements are welcome.
529.SS "Editor commands (+)"
530`bindkey' lists key bindings and `bindkey \-l' lists and briefly describes
531editor commands.
532Only new or especially interesting editor commands are described here.
533See \fIemacs\fR(1) and \fIvi\fR(1) for descriptions of each editor's
534key bindings.
535.PP
536The character or characters to which each command is bound by default is
537given in parentheses.  `^\fIcharacter\fR' means a control character and
538`M-\fIcharacter\fR' a meta character, typed as escape-\fIcharacter\fR
539on terminals without a meta key.  Case counts, but commands that are bound
540to letters by default are bound to both lower- and uppercase letters for
541convenience.
542.TP 8
543.B complete-word \fR(tab)
544Completes a word as described under \fBCompletion and listing\fR.
545.TP 8
546.B complete-word-back \fR(not bound)
547Like \fIcomplete-word-fwd\fR, but steps up from the end of the list.
548.TP 8
549.B complete-word-fwd \fR(not bound)
550Replaces the current word with the first word in the list of possible
551completions.  May be repeated to step down through the list.
552At the end of the list, beeps and reverts to the incomplete word.
553.TP 8
554.B complete-word-raw \fR(^X-tab)
555Like \fIcomplete-word\fR, but ignores user-defined completions.
556.TP 8
557.B copy-prev-word \fR(M-^_)
558Copies the previous word in the current line into the input buffer.
559See also \fIinsert-last-word\fR.
560.TP 8
561.B dabbrev-expand \fR(M-/)
562Expands the current word to the most recent preceding one for which
563the current is a leading substring, wrapping around the history list
564(once) if necessary.
565Repeating \fIdabbrev-expand\fR without any intervening typing
566changes to the next previous word etc., skipping identical matches
567much like \fIhistory-search-backward\fR does.
568.TP 8
569.B delete-char \fR(not bound)
570Deletes the character under the cursor.
571See also \fIdelete-char-or-list-or-eof\fR.
572.TP 8
573.B delete-char-or-eof \fR(not bound)
574Does \fIdelete-char\fR if there is a character under the cursor
575or \fIend-of-file\fR on an empty line.
576See also \fIdelete-char-or-list-or-eof\fR.
577.TP 8
578.B delete-char-or-list \fR(not bound)
579Does \fIdelete-char\fR if there is a character under the cursor
580or \fIlist-choices\fR at the end of the line.
581See also \fIdelete-char-or-list-or-eof\fR.
582.TP 8
583.B delete-char-or-list-or-eof \fR(^D)
584Does \fIdelete-char\fR if there is a character under the cursor,
585\fIlist-choices\fR at the end of the line
586or \fIend-of-file\fR on an empty line.
587See also those three commands, each of which does only a single action, and
588\fIdelete-char-or-eof\fR, \fIdelete-char-or-list\fR and \fIlist-or-eof\fR,
589each of which does a different two out of the three.
590.TP 8
591.B down-history \fR(down-arrow, ^N)
592Like \fIup-history\fR, but steps down, stopping at the original input line.
593.TP 8
594.B end-of-file \fR(not bound)
595Signals an end of file, causing the shell to exit unless the \fBignoreeof\fR
596shell variable (q.v.) is set to prevent this.
597See also \fIdelete-char-or-list-or-eof\fR.
598.TP 8
599.B expand-history \fR(M-space)
600Expands history substitutions in the current word.
601See \fBHistory substitution\fR.
602See also \fImagic-space\fR, \fItoggle-literal-history\fR and
603the \fBautoexpand\fR shell variable.
604.TP 8
605.B expand-glob \fR(^X-*)
606Expands the glob-pattern to the left of the cursor.
607See \fBFilename substitution\fR.
608.TP 8
609.B expand-line \fR(not bound)
610Like \fIexpand-history\fR, but
611expands history substitutions in each word in the input buffer,
612.TP 8
613.B expand-variables \fR(^X-$)
614Expands the variable to the left of the cursor.
615See \fBVariable substitution\fR.
616.TP 8
617.B history-search-backward \fR(M-p, M-P)
618Searches backwards through the history list for a command beginning with
619the current contents of the input buffer up to the cursor and copies it
620into the input buffer.
621The search string may be a glob-pattern (see \fBFilename substitution\fR)
622containing `*', `?', `[]' or `{}'.
623\fIup-history\fR and \fIdown-history\fR will proceed from the
624appropriate point in the history list.
625Emacs mode only.
626See also \fIhistory-search-forward\fR and \fIi-search-back\fR.
627.TP 8
628.B history-search-forward \fR(M-n, M-N)
629Like \fIhistory-search-backward\fR, but searches forward.
630.TP 8
631.B i-search-back \fR(not bound)
632Searches backward like \fIhistory-search-backward\fR, copies the first match
633into the input buffer with the cursor positioned at the end of the pattern,
634and prompts with `bck: ' and the first match.  Additional characters may be
635typed to extend the search, \fIi-search-back\fR may be typed to continue
636searching with the same pattern, wrapping around the history list if
637necessary, (\fIi-search-back\fR must be bound to a
638single character for this to work) or one of the following special characters
639may be typed:
640.PP
641.RS +8
642.RS +4
643.PD 0
644.TP 8
645^W
646Appends the rest of the word under the cursor to the search pattern.
647.TP 8
648delete (or any character bound to \fIbackward-delete-char\fR)
649Undoes the effect of the last character typed and deletes a character
650from the search pattern if appropriate.
651.TP 8
652^G
653If the previous search was successful, aborts the entire search.
654If not, goes back to the last successful search.
655.TP 8
656escape
657Ends the search, leaving the current line in the input buffer.
658.RE
659.PD
660.PP
661Any other character not bound to \fIself-insert-command\fR terminates the
662search, leaving the current line in the input buffer, and
663is then interpreted as normal input.  In particular, a carriage return
664causes the current line to be executed.
665Emacs mode only.
666See also \fIi-search-fwd\fR and \fIhistory-search-backward\fR.
667.RE
668.TP 8
669.B i-search-fwd \fR(not bound)
670Like \fIi-search-back\fR, but searches forward.
671.TP 8
672.B insert-last-word \fR(M-_)
673Inserts the last word of the previous input line (`!$') into the input buffer.
674See also \fIcopy-prev-word\fR.
675.TP 8
676.B list-choices \fR(M-^D)
677Lists completion possibilities as described under \fBCompletion and listing\fR.
678See also \fIdelete-char-or-list-or-eof\fR and \fIlist-choices-raw\fR.
679.TP 8
680.B list-choices-raw \fR(^X-^D)
681Like \fIlist-choices\fR, but ignores user-defined completions.
682.TP 8
683.B list-glob \fR(^X-g, ^X-G)
684Lists (via the \fIls\-F\fR builtin) matches to the glob-pattern
685(see \fBFilename substitution\fR) to the left of the cursor.
686.TP 8
687.B list-or-eof \fR(not bound)
688Does \fIlist-choices\fR
689or \fIend-of-file\fR on an empty line.
690See also \fIdelete-char-or-list-or-eof\fR.
691.TP 8
692.B magic-space \fR(not bound)
693Expands history substitutions in the current line,
694like \fIexpand-history\fR, and inserts a space.
695\fImagic-space\fR is designed to be bound to the space bar,
696but is not bound by default.
697.TP 8
698.B normalize-command \fR(^X-?)
699Searches for the current word in PATH and, if it is found, replaces it with
700the full path to the executable.  Special characters are quoted.  Aliases are
701expanded and quoted but commands within aliases are not.  This command is
702useful with commands that take commands as arguments, e.g., `dbx' and `sh \-x'.
703.TP 8
704.B normalize-path \fR(^X-n, ^X-N)
705Expands the current word as described under the `expand' setting
706of the \fBsymlinks\fR shell variable.
707.TP 8
708.B overwrite-mode \fR(unbound)
709Toggles between input and overwrite modes.
710.TP 8
711.B run-fg-editor \fR(M-^Z)
712Saves the current input line and
713looks for a stopped job with a name equal to the last component of the
714file name part of the \fBEDITOR\fR or \fBVISUAL\fR environment variables,
715or, if neither is set, `ed' or `vi'.
716If such a job is found, it is restarted as if `fg %\fIjob\fR' had been
717typed.  This is used to toggle back and forth between an editor and
718the shell easily.  Some people bind this command to `^Z' so they
719can do this even more easily.
720.TP
721.B run-help \fR(M-h, M-H)
722Searches for documentation on the current command, using the same notion of
723`current command' as the completion routines, and prints it.  There is no way
724to use a pager; \fIrun-help\fR is designed for short help files.
725If the special alias \fBhelpcommand\fR is defined, it is run with the
726command name as a sole argument.  Else,
727documentation should be in a file named \fIcommand\fR.help, \fIcommand\fR.1,
728\fIcommand\fR.6, \fIcommand\fR.8 or \fIcommand\fR, which should be in one
729of the directories listed in the \fBHPATH\fR environment variable.
730If there is more than one help file only the first is printed.
731.TP 8
732.B self-insert-command \fR(text characters)
733In insert mode (the default), inserts the typed character into the input line after the character under the cursor.
734In overwrite mode, replaces the character under the cursor with the typed character.
735The input mode is normally preserved between lines, but the
736\fBinputmode\fR shell variable can be set to `insert' or `overwrite' to put the
737editor in that mode at the beginning of each line.
738See also \fIoverwrite-mode\fR.
739.TP 8
740.B sequence-lead-in \fR(arrow prefix, meta prefix, ^X)
741Indicates that the following characters are part of a
742multi-key sequence.  Binding a command to a multi-key sequence really creates
743two bindings: the first character to \fIsequence-lead-in\fR and the
744whole sequence to the command.  All sequences beginning with a character
745bound to \fIsequence-lead-in\fR are effectively bound to \fIundefined-key\fR
746unless bound to another command.
747.TP 8
748.B spell-line \fR(M-$)
749Attempts to correct the spelling of each word in the input buffer, like
750\fIspell-word\fR, but ignores words whose first character is one of
751`\-', `!', `^' or `%', or which contain `\\', `*' or `?', to avoid problems
752with switches, substitutions and the like.
753See \fBSpelling correction\fR.
754.TP 8
755.B spell-word \fR(M-s, M-S)
756Attempts to correct the spelling of the current word as described
757under \fBSpelling correction\fR.
758Checks each component of a word which appears to be a pathname.
759.TP 8
760.B toggle-literal-history \fR(M-r, M-R)
761Expands or `unexpands' history substitutions in the input buffer.
762See also \fIexpand-history\fR and the \fBautoexpand\fR shell variable.
763.TP 8
764.B undefined-key \fR(any unbound key)
765Beeps.
766.TP 8
767.B up-history \fR(up-arrow, ^P)
768Copies the previous entry in the history list into the input buffer.
769If \fBhistlit\fR is set, uses the literal form of the entry.
770May be repeated to step up through the history list, stopping at the top.
771.TP 8
772.B vi-search-back \fR(?)
773Prompts with `?' for a search string (which may be a glob-pattern, as with
774\fIhistory-search-backward\fR), searches for it and copies it into the
775input buffer.  The bell rings if no match is found.
776Hitting return ends the search and leaves the last match in the input
777buffer.
778Hitting escape ends the search and executes the match.
779\fIvi\fR mode only.
780.TP 8
781.B vi-search-fwd \fR(/)
782Like \fIvi-search-back\fR, but searches forward.
783.TP 8
784.B which-command \fR(M-?)
785Does a \fIwhich\fR (see the description of the builtin command) on the
786first word of the input buffer.
787.TP 8
788.B yank-pop \fR(M-y)
789When executed immediately after a \fIyank\fR or another \fIyank-pop\fR,
790replaces the yanked string with the next previous string from the
791killring. This also has the effect of rotating the killring, such that
792this string will be considered the most recently killed by a later
793\fIyank\fR command. Repeating \fIyank-pop\fR will cycle through the
794killring any number of times.
795.SS "Lexical structure"
796The shell splits input lines into words at blanks and tabs.  The special
797characters `&', `|', `;', `<', `>', `(', and `)' and the doubled characters
798`&&', `||', `<<' and `>>' are always separate words, whether or not they are
799surrounded by whitespace.
800.PP
801When the shell's input is not a terminal, the character `#' is taken to begin a
802comment.  Each `#' and the rest of the input line on which it appears is
803discarded before further parsing.
804.PP
805A special character (including a blank or tab) may be prevented from having
806its special meaning, and possibly made part of another word, by preceding it
807with a backslash (`\\') or enclosing it in single (`''), double (`"') or
808backward (``') quotes.  When not otherwise quoted a newline preceded by a `\\'
809is equivalent to a blank, but inside quotes this sequence results in a
810newline.
811.PP
812Furthermore, all \fBSubstitutions\fR (see below) except \fBHistory substitution\fR
813can be prevented by enclosing the strings (or parts of strings)
814in which they appear with single quotes or by quoting the crucial character(s)
815(e.g., `$' or ``' for \fBVariable substitution\fR or \fBCommand substitution\fR respectively)
816with `\\'.  (\fBAlias substitution\fR is no exception: quoting in any way any
817character of a word for which an \fIalias\fR has been defined prevents
818substitution of the alias.  The usual way of quoting an alias is to precede it
819with a backslash.) \fBHistory substitution\fR is prevented by
820backslashes but not by single quotes.  Strings quoted with double or backward
821quotes undergo \fBVariable substitution\fR and \fBCommand substitution\fR, but other
822substitutions are prevented.
823.PP
824Text inside single or double quotes becomes a single word (or part of one).
825Metacharacters in these strings, including blanks and tabs, do not form
826separate words.  Only in one special case (see \fBCommand substitution\fR
827below) can a double-quoted string yield parts of more than one word;
828single-quoted strings never do.  Backward quotes are special: they signal
829\fBCommand substitution\fR (q.v.), which may result in more than one word.
830.PP
831Quoting complex strings, particularly strings which themselves contain quoting
832characters, can be confusing.  Remember that quotes need not be used as they are
833in human writing!  It may be easier to quote not an entire string, but only
834those parts of the string which need quoting, using different types of quoting
835to do so if appropriate.
836.PP
837The \fBbackslash_quote\fR shell variable (q.v.) can be set to make backslashes
838always quote `\\', `'', and `"'.  (+) This may make complex quoting tasks
839easier, but it can cause syntax errors in \fIcsh\fR(1) scripts.
840.SS Substitutions
841We now describe the various transformations the shell performs on the input in
842the order in which they occur.  We note in passing the data structures involved
843and the commands and variables which affect them.  Remember that substitutions
844can be prevented by quoting as described under \fBLexical structure\fR.
845.SS "History substitution"
846Each command, or ``event'', input from the terminal is saved in the history
847list.  The previous command is always saved, and the \fBhistory\fR shell
848variable can be set to a number to save that many commands.  The \fBhistdup\fR
849shell variable can be set to not save duplicate events or consecutive duplicate
850events.
851.PP
852Saved commands are numbered sequentially from 1 and stamped with the time.
853It is not usually necessary to use event numbers, but the current event number
854can be made part of the prompt by placing an `!' in the \fBprompt\fR shell variable.
855.PP
856The shell actually saves history in expanded and literal (unexpanded) forms.
857If the \fBhistlit\fR shell variable is set, commands that display and store
858history use the literal form.
859.PP
860The \fIhistory\fR builtin command can print, store in a file, restore
861and clear the history list at any time,
862and the \fBsavehist\fR and \fBhistfile\fR shell variables can be can be set to
863store the history list automatically on logout and restore it on login.
864.PP
865History substitutions introduce words from the history list into the input
866stream, making it easy to repeat commands, repeat arguments of a previous
867command in the current command, or fix spelling mistakes in the previous
868command with little typing and a high degree of confidence.
869.PP
870History substitutions begin with the character `!'.  They may begin anywhere in
871the input stream, but they do not nest.  The `!' may be preceded by a `\\' to
872prevent its special meaning; for convenience, a `!' is passed unchanged when it
873is followed by a blank, tab, newline, `=' or `('.  History substitutions also
874occur when an input line begins with `^'.  This special abbreviation will be
875described later.  The characters used to signal history substitution (`!' and
876`^') can be changed by setting the \fBhistchars\fR shell variable.  Any input
877line which contains a history substitution is printed before it is executed.
878.PP
879A history substitution may have an ``event specification'', which indicates
880the event from which words are to be taken, a ``word designator'',
881which selects particular words from the chosen event, and/or a ``modifier'',
882which manipulates the selected words.
883.PP
884An event specification can be
885.PP
886.PD 0
887.RS +4
888.TP 8
889.I n
890A number, referring to a particular event
891.TP 8
892\-\fIn\fR
893An offset, referring to the event \fIn\fR before the current event
894.TP 8
895#
896The current event.
897This should be used carefully in \fIcsh\fR(1), where there is no check for
898recursion.  \fItcsh\fR allows 10 levels of recursion.  (+)
899.TP 8
900!
901The previous event (equivalent to `\-1')
902.TP 8
903.I s
904The most recent event whose first word begins with the string \fIs\fR
905.TP 8
906?\fIs\fR?
907The most recent event which contains the string \fIs\fR.
908The second `?' can be omitted if it is immediately followed by a newline.
909.RE
910.PD
911.PP
912For example, consider this bit of someone's history list:
913.IP "" 4
914\ 9  8:30    nroff \-man wumpus.man
915.br
91610  8:31    cp wumpus.man wumpus.man.old
917.br
91811  8:36    vi wumpus.man
919.br
92012  8:37    diff wumpus.man.old wumpus.man
921.PP
922The commands are shown with their event numbers and time stamps.
923The current event, which we haven't typed in yet, is event 13.
924`!11' and `!\-2' refer to event 11.
925`!!' refers to the previous event, 12.  `!!' can be abbreviated `!' if it is
926followed by `:' (`:' is described below).
927`!n' refers to event 9, which begins with `n'.
928`!?old?' also refers to event 12, which contains `old'.
929Without word designators or modifiers history references simply expand to the
930entire event, so we might type `!cp' to redo the copy command or `!!|more'
931if the `diff' output scrolled off the top of the screen.
932.PP
933History references may be insulated from the surrounding text with braces if
934necessary.  For example, `!vdoc' would look for a command beginning with
935`vdoc', and, in this example, not find one, but `!{v}doc' would expand
936unambiguously to `vi wumpus.mandoc'.
937Even in braces, history substitutions do not nest.
938.PP
939(+) While \fIcsh\fR(1) expands, for example, `!3d' to event 3 with the
940letter `d' appended to it, \fItcsh\fR expands it to the last event beginning
941with `3d'; only completely numeric arguments are treated as event numbers.
942This makes it possible to recall events beginning with numbers.
943To expand `!3d' as in \fIcsh\fR(1) say `!\\3d'.
944.PP
945To select words from an event we can follow the event specification by a `:'
946and a designator for the desired words.  The words of an input line are
947numbered from 0, the first (usually command) word being 0, the second word
948(first argument) being 1, etc.  The basic word designators are:
949.PP
950.PD 0
951.RS +4
952.TP 8
9530
954The first (command) word
955.TP 8
956.I n
957The \fIn\fRth argument
958.TP 8
959^
960The first argument, equivalent to `1'
961.TP 8
962$
963The last argument
964.TP 8
965%
966The word matched by an ?\fIs\fR? search
967.TP 8
968.I x\-y
969A range of words
970.TP 8
971.I \-y
972Equivalent to \fI`0\-y'\fR
973.TP 8
974*
975Equivalent to `^\-$', but returns nothing if the event contains only 1 word
976.TP 8
977.I x*
978Equivalent to \fI`x\-$'\fR
979.TP 8
980.I x\-
981Equivalent to \fI`x*'\fR, but omitting the last word (`$')
982.PD
983.RE
984.PP
985Selected words are inserted into the command line separated by single blanks.
986For example, the `diff' command in the previous example might have been
987typed as `diff !!:1.old !!:1' (using `:1' to select the first argument
988from the previous event) or `diff !\-2:2 !\-2:1' to select and swap the
989arguments from the `cp' command.  If we didn't care about the order of the
990`diff' we might have said `diff !\-2:1\-2' or simply `diff !\-2:*'.
991The `cp' command might have been written `cp wumpus.man !#:1.old', using `#'
992to refer to the current event.
993`!n:\- hurkle.man' would reuse the first two words from the `nroff' command
994to say `nroff \-man hurkle.man'.
995.PP
996The `:' separating the event specification from the word designator can be
997omitted if the argument selector begins with a `^', `$', `*', `%' or `\-'.
998For example, our `diff' command might have been `diff !!^.old !!^' or,
999equivalently, `diff !!$.old !!$'.  However, if `!!' is abbreviated `!',
1000an argument selector beginning with `\-' will be interpreted as an event
1001specification.
1002.PP
1003A history reference may have a word designator but no event specification.
1004It then references the previous command.
1005Continuing our `diff' example, we could have said simply `diff
1006!^.old !^' or, to get the arguments in the opposite order, just `diff !*'.
1007.PP
1008The word or words in a history reference can be edited, or ``modified'',
1009by following it with one or more modifiers, each preceded by a `:':
1010.PP
1011.PD 0
1012.RS +4
1013.TP 8
1014h
1015Remove a trailing pathname component, leaving the head.
1016.TP 8
1017t
1018Remove all leading pathname components, leaving the tail.
1019.TP 8
1020r
1021Remove a filename extension `.xxx', leaving the root name.
1022.TP 8
1023e
1024Remove all but the extension.
1025.TP 8
1026u
1027Uppercase the first lowercase letter.
1028.TP 8
1029l
1030Lowercase the first uppercase letter.
1031.TP 8
1032s\fI/l/r/\fR
1033Substitute \fIl\fR for \fIr\fR.
1034\fIl\fR is simply a string like \fIr\fR, not a regular expression as in
1035the eponymous \fIed\fR(1) command.
1036Any character may be used as the delimiter in place of `/';
1037a `\\' can be used to quote the delimiter inside \fIl\fR and \fIr\fR.
1038The character `&' in the \fIr\fR is replaced by \fIl\fR; `\\' also quotes `&'.
1039If \fIl\fR is empty (``''), the \fIl\fR from a previous substitution or the
1040\fIs\fR from a previous `?\fIs\fR?' event specification is used.
1041The trailing delimiter may be omitted if it is immediately followed by a newline.
1042.TP 8
1043&
1044Repeat the previous substitution.
1045.TP 8
1046g
1047Apply the following modifier once to each word.
1048.TP 8
1049a (+)
1050Apply the following modifier as many times as possible to a single word.
1051`a' and `g' can be used together to apply a modifier globally.
1052In the current implementation, using the `a' and `s' modifiers together can
1053lead to an infinite loop.  For example, `:as/f/ff/' will never terminate.
1054This behavior might change in the future.
1055.TP 8
1056p
1057Print the new command line but do not execute it.
1058.TP 8
1059q
1060Quote the substituted words, preventing further substitutions.
1061.TP 8
1062x
1063Like q, but break into words at blanks, tabs and newlines.
1064.PD
1065.RE
1066.PP
1067Modifiers are applied to only the first modifiable word (unless `g' is used).
1068It is an error for no word to be modifiable.
1069.PP
1070For example, the `diff' command might have been written as `diff wumpus.man.old
1071!#^:r', using `:r' to remove `.old' from the first argument on the same line
1072(`!#^').  We could say `echo hello out there', then `echo !*:u' to capitalize
1073`hello', `echo !*:au' to say it out loud, or `echo !*:agu' to really shout.
1074We might follow `mail \-s "I forgot my password" rot' with `!:s/rot/root' to
1075correct the spelling of `root' (but see \fBSpelling correction\fR for a
1076different approach).
1077.PP
1078There is a special abbreviation for substitutions.
1079`^', when it is the first character on an input line, is equivalent to `!:s^'.
1080Thus we might have said `^rot^root' to make the spelling correction in the
1081previous example.
1082This is the only history substitution which does not explicitly begin with `!'.
1083.PP
1084(+) In \fIcsh\fR as such, only one modifier may be applied to each history
1085or variable expansion.  In \fItcsh\fR, more than one may be used, for example
1086.IP "" 4
1087% mv wumpus.man /usr/man/man1/wumpus.1
1088.br
1089% man !$:t:r
1090.br
1091man wumpus
1092.PP
1093In \fIcsh\fR, the result would be `wumpus.1:r'.  A substitution followed by a
1094colon may need to be insulated from it with braces:
1095.IP "" 4
1096> mv a.out /usr/games/wumpus
1097.br
1098> setenv PATH !$:h:$PATH
1099.br
1100Bad ! modifier: $.
1101.br
1102> setenv PATH !{\-2$:h}:$PATH
1103.br
1104setenv PATH /usr/games:/bin:/usr/bin:.
1105.PP
1106The first attempt would succeed in \fIcsh\fR but fails in \fItcsh\fR,
1107because \fItcsh\fR expects another modifier after the second colon
1108rather than `$'.
1109.PP
1110Finally, history can be accessed through the editor as well as through
1111the substitutions just described.
1112The \fIup-\fR and \fIdown-history\fR, \fIhistory-search-backward\fR and
1113\fI-forward\fR, \fIi-search-back\fR and \fI-fwd\fR,
1114\fIvi-search-back\fR and \fI-fwd\fR, \fIcopy-prev-word\fR
1115and \fIinsert-last-word\fR editor commands search for
1116events in the history list and copy them into the input buffer.
1117The \fItoggle-literal-history\fR editor command switches between the
1118expanded and literal forms of history lines in the input buffer.
1119\fIexpand-history\fR and \fIexpand-line\fR expand history substitutions
1120in the current word and in the entire input buffer respectively.
1121.SS "Alias substitution"
1122The shell maintains a list of aliases which can be set, unset and printed by
1123the \fIalias\fR and \fIunalias\fR commands.  After a command line is parsed
1124into simple commands (see \fBCommands\fR) the first word of each command,
1125left-to-right, is checked to see if it has an alias.  If so, the first word is
1126replaced by the alias.  If the alias contains a history reference, it undergoes
1127\fBHistory substitution\fR (q.v.) as though the original command were the
1128previous input line.  If the alias does not contain a history reference, the
1129argument list is left untouched.
1130.PP
1131Thus if the alias for `ls' were `ls \-l' the command `ls /usr' would become `ls
1132\-l /usr', the argument list here being undisturbed.  If the alias for `lookup'
1133were `grep !^ /etc/passwd' then `lookup bill' would become `grep bill
1134/etc/passwd'.  Aliases can be used to introduce parser metasyntax.  For
1135example, `alias print 'pr \e!* | lpr'' defines a ``command'' (`print') which
1136\fIpr\fR(1)s its arguments to the line printer.
1137.PP
1138Alias substitution is repeated until the first word of the command has no
1139alias.  If an alias substitution does not change the first word (as in the
1140previous example) it is flagged to prevent a loop.  Other loops are detected and
1141cause an error.
1142.PP
1143Some aliases are referred to by the shell; see \fBSpecial aliases\fR.
1144.SS "Variable substitution"
1145The shell maintains a list of variables, each of which has as value a list of
1146zero or more words.
1147The values of shell variables can be displayed and changed with the
1148\fIset\fR and \fIunset\fR commands.
1149The system maintains its own list of ``environment'' variables.
1150These can be displayed and changed with \fIprintenv\fR, \fIsetenv\fR and
1151\fIunsetenv\fR.
1152.PP
1153(+) Variables may be made read-only with `set \-r' (q.v.)
1154Read-only variables may not be modified or unset;
1155attempting to do so will cause an error.
1156Once made read-only, a variable cannot be made writable,
1157so `set \-r' should be used with caution.
1158Environment variables cannot be made read-only.
1159.PP
1160Some variables are set by the shell or referred to by it.
1161For instance, the \fBargv\fR variable is an image of the shell's argument
1162list, and words of this variable's value are referred to in special ways.
1163Some of the variables referred to by the shell are toggles;
1164the shell does not care what their value is, only whether they are set or not.
1165For instance, the \fBverbose\fR variable is a toggle which causes command
1166input to be echoed.  The \fB\-v\fR command line option sets this variable.
1167\fBSpecial shell variables\fR lists all variables which are referred to by the shell.
1168.PP
1169Other operations treat variables numerically.  The `@' command permits numeric
1170calculations to be performed and the result assigned to a variable.  Variable
1171values are, however, always represented as (zero or more) strings.  For the
1172purposes of numeric operations, the null string is considered to be zero, and
1173the second and subsequent words of multi-word values are ignored.
1174.PP
1175After the input line is aliased and parsed, and before each command is
1176executed, variable substitution is performed keyed by `$' characters.  This
1177expansion can be prevented by preceding the `$' with a `\e' except within `"'s
1178where it \fIalways\fR occurs, and within `''s where it \fInever\fR occurs.
1179Strings quoted by ``' are interpreted later (see \fBCommand substitution\fR
1180below) so `$' substitution does not occur there until later,
1181if at all.  A `$' is passed unchanged if followed by a blank, tab, or
1182end-of-line.
1183.PP
1184Input/output redirections are recognized before variable expansion, and are
1185variable expanded separately.  Otherwise, the command name and entire argument
1186list are expanded together.  It is thus possible for the first (command) word
1187(to this point) to generate more than one word, the first of which becomes the
1188command name, and the rest of which become arguments.
1189.PP
1190Unless enclosed in `"' or given the `:q' modifier the results of variable
1191substitution may eventually be command and filename substituted.  Within `"', a
1192variable whose value consists of multiple words expands to a (portion of a)
1193single word, with the words of the variable's value separated by blanks.  When
1194the `:q' modifier is applied to a substitution the variable will expand to
1195multiple words with each word separated by a blank and quoted to prevent later
1196command or filename substitution.
1197.PP
1198The following metasequences are provided for introducing variable values into
1199the shell input.  Except as noted, it is an error to reference a variable which
1200is not set.
1201.PP
1202.PD 0
1203$\fIname\fR
1204.TP 8
1205${\fIname\fR}
1206Substitutes the words of the value of variable \fIname\fR, each separated
1207by a blank.  Braces insulate \fIname\fR from following characters which would
1208otherwise be part of it.  Shell variables have names consisting of up to 20
1209letters and digits starting with a letter.  The underscore character is
1210considered a letter.  If \fIname\fR is not a shell variable, but is set in the
1211environment, then that value is returned (but `:' modifiers and the other forms
1212given below are not available in this case).
1213.PP
1214$\fIname\fR[\fIselector\fR]
1215.TP 8
1216${\fIname\fR[\fIselector\fR]}
1217Substitutes only the selected words from the value of \fIname\fR.
1218The \fIselector\fR is subjected to `$' substitution and may consist of
1219a single number or two numbers separated by a `\-'.
1220The first word of a variable's value is numbered `1'.
1221If the first number of a range is omitted it defaults to `1'.
1222If the last member of a range is omitted it defaults to `$#\fIname\fR'.
1223The \fIselector\fR `*' selects all words.
1224It is not an error for a range to be empty if the
1225second argument is omitted or in range.
1226.TP 8
1227$0
1228Substitutes the name of the file from which command input
1229is being read.  An error occurs if the name is not known.
1230.PP
1231$\fInumber\fR
1232.TP 8
1233${\fInumber\fR}
1234Equivalent to `$argv[\fInumber\fR]'.
1235.TP 8
1236$*
1237Equivalent to `$argv', which is equivalent to `$argv[*]'.
1238.PD
1239.PP
1240The `:' modifiers described under \fBHistory substitution\fR, except for `:p',
1241can be applied to the substitutions above.  More than one may be used.  (+)
1242Braces may be needed to insulate a variable substitution from a literal colon
1243just as with \fBHistory substitution\fR (q.v.); any modifiers must appear
1244within the braces.
1245.PP
1246The following substitutions can not be modified with `:' modifiers.
1247.PP
1248.PD 0
1249$?\fIname\fR
1250.TP 8
1251${?\fIname\fR}
1252Substitutes the string `1' if \fIname\fR is set, `0' if it is not.
1253.TP 8
1254$?0
1255Substitutes `1' if the current input filename is known, `0' if it is not.
1256Always `0' in interactive shells.
1257.PP
1258$#\fIname\fR
1259.TP 8
1260${#\fIname\fR}
1261Substitutes the number of words in \fIname\fR.
1262.TP 8
1263$#
1264Equivalent to `$#argv'.  (+)
1265.PP
1266$%\fIname\fR
1267.TP 8
1268${%\fIname\fR}
1269Substitutes the number of characters in \fIname\fR.  (+)
1270.PP
1271$%\fInumber\fR
1272.TP 8
1273${%\fInumber\fR}
1274Substitutes the number of characters in $argv[\fInumber\fR].  (+)
1275.TP 8
1276$?
1277Equivalent to `$status'.  (+)
1278.TP 8
1279$$
1280Substitutes the (decimal) process number of the (parent) shell.
1281.TP 8
1282$!
1283Substitutes the (decimal) process number of the last
1284background process started by this shell.  (+)
1285.TP 8
1286$_
1287Substitutes the command line of the last command executed.  (+)
1288.TP 8
1289$<
1290Substitutes a line from the standard input, with no further interpretation
1291thereafter.  It can be used to read from the keyboard in a shell script.
1292(+) While \fIcsh\fR always quotes $<, as if it were equivalent to `$<:q',
1293\fItcsh\fR does not.  Furthermore, when \fItcsh\fR is waiting for a line to be
1294typed the user may type an interrupt to interrupt the sequence into
1295which the line is to be substituted, but \fIcsh\fR does not allow this.
1296.PD
1297.PP
1298The editor command \fIexpand-variables\fR, normally bound to `^X-$',
1299can be used to interactively expand individual variables.
1300.SS "Command, filename and directory stack substitution"
1301The remaining substitutions are applied selectively to the arguments of builtin
1302commands.  This means that portions of expressions which are not evaluated are
1303not subjected to these expansions.  For commands which are not internal to the
1304shell, the command name is substituted separately from the argument list.  This
1305occurs very late, after input-output redirection is performed, and in a child
1306of the main shell.
1307.SS "Command substitution"
1308Command substitution is indicated by a command enclosed in ``'.  The output
1309from such a command is broken into separate words at blanks, tabs and newlines,
1310and null words are discarded.  The output is variable and command substituted
1311and put in place of the original string.
1312.PP
1313Command substitutions inside double
1314quotes (`"') retain blanks and tabs; only newlines force new words.  The single
1315final newline does not force a new word in any case.  It is thus possible for a
1316command substitution to yield only part of a word, even if the command outputs
1317a complete line.
1318.PP
1319By default, the shell since version 6.12 replaces all newline and carriage
1320return characters in the command by spaces.  If this is switched off by
1321unsetting \fBcsubstnonl\fR, newlines separate commands as usual.
1322.SS "Filename substitution"
1323If a word contains any of the characters `*', `?', `[' or `{' or begins with
1324the character `~' it is a candidate for filename substitution, also known as
1325``globbing''.  This word is then regarded as a pattern (``glob-pattern''), and
1326replaced with an alphabetically sorted list of file names which match the
1327pattern.
1328.PP
1329In matching filenames, the character `.' at the beginning of a filename or
1330immediately following a `/', as well as the character `/' must be matched
1331explicitly.  The character `*' matches any string of characters, including the
1332null string.  The character `?' matches any single character.  The sequence
1333`[...]' matches any one of the characters enclosed.  Within `[...]', a pair of
1334characters separated by `\-' matches any character lexically between the two.
1335.PP
1336(+) Some glob-patterns can be negated:
1337The sequence `[^...]' matches any single character \fInot\fR specified by the
1338characters and/or ranges of characters in the braces.
1339.PP
1340An entire glob-pattern can also be negated with `^':
1341.IP "" 4
1342> echo *
1343.br
1344bang crash crunch ouch
1345.br
1346> echo ^cr*
1347.br
1348bang ouch
1349.PP
1350Glob-patterns which do not use `?', `*', or `[]' or which use `{}' or `~'
1351(below) are not negated correctly.
1352.PP
1353The metanotation `a{b,c,d}e' is a shorthand for `abe ace ade'.
1354Left-to-right order is preserved: `/usr/source/s1/{oldls,ls}.c' expands
1355to `/usr/source/s1/oldls.c /usr/source/s1/ls.c'.  The results of matches are
1356sorted separately at a low level to preserve this order:
1357`../{memo,*box}' might expand to `../memo ../box ../mbox'.
1358(Note that `memo' was not sorted with the results of matching `*box'.)
1359It is not an error when this construct expands to files which do not exist,
1360but it is possible to get an error from a command to which the expanded list
1361is passed.
1362This construct may be nested.
1363As a special case the words `{', `}' and `{}' are passed undisturbed.
1364.PP
1365The character `~' at the beginning of a filename refers to home directories.
1366Standing alone, i.e., `~', it expands to the invoker's home directory as
1367reflected in the value of the \fBhome\fR shell variable.  When followed by a
1368name consisting of letters, digits and `\-' characters the shell searches for a
1369user with that name and substitutes their home directory; thus `~ken' might
1370expand to `/usr/ken' and `~ken/chmach' to `/usr/ken/chmach'.  If the character
1371`~' is followed by a character other than a letter or `/' or appears elsewhere
1372than at the beginning of a word, it is left undisturbed.
1373A command like `setenv MANPATH /usr/man:/usr/local/man:~/lib/man' does not,
1374therefore, do home directory substitution as one might hope.
1375.PP
1376It is an error for a glob-pattern containing `*', `?', `[' or `~', with or
1377without `^', not to match any files.  However, only one pattern in a list of
1378glob-patterns must match a file (so that, e.g., `rm *.a *.c *.o' would fail
1379only if there were no files in the current directory ending in `.a', `.c', or
1380`.o'), and if the \fBnonomatch\fR shell variable is set a pattern (or list
1381of patterns) which matches nothing is left unchanged rather than causing
1382an error.
1383.PP
1384The \fBnoglob\fR shell variable can be set to prevent filename substitution,
1385and the \fIexpand-glob\fR editor command, normally bound to `^X-*', can be
1386used to interactively expand individual filename substitutions.
1387.SS "Directory stack substitution (+)"
1388The directory stack is a list of directories, numbered from zero, used by the
1389\fIpushd\fR, \fIpopd\fR and \fIdirs\fR builtin commands (q.v.).
1390\fIdirs\fR can print, store in a file, restore and clear the directory stack
1391at any time, and the \fBsavedirs\fR and \fBdirsfile\fR shell variables can be set to
1392store the directory stack automatically on logout and restore it on login.
1393The \fBdirstack\fR shell variable can be examined to see the directory stack and
1394set to put arbitrary directories into the directory stack.
1395.PP
1396The character `=' followed by one or more digits expands to an entry in
1397the directory stack.  The special case `=\-' expands to the last directory in
1398the stack.  For example,
1399.IP "" 4
1400> dirs \-v
1401.br
14020       /usr/bin
1403.br
14041       /usr/spool/uucp
1405.br
14062       /usr/accts/sys
1407.br
1408> echo =1
1409.br
1410/usr/spool/uucp
1411.br
1412> echo =0/calendar
1413.br
1414/usr/bin/calendar
1415.br
1416> echo =\-
1417.br
1418/usr/accts/sys
1419.PP
1420The \fBnoglob\fR and \fBnonomatch\fR shell variables and the \fIexpand-glob\fR
1421editor command apply to directory stack as well as filename substitutions.
1422.SS "Other substitutions (+)"
1423There are several more transformations involving filenames, not strictly
1424related to the above but mentioned here for completeness.
1425\fIAny\fR filename may be expanded to a full path when the
1426\fBsymlinks\fR variable (q.v.) is set to `expand'.
1427Quoting prevents this expansion, and
1428the \fInormalize-path\fR editor command does it on demand.
1429The \fInormalize-command\fR editor command expands commands in PATH into
1430full paths on demand.
1431Finally, \fIcd\fR and \fIpushd\fR interpret `\-' as the old working directory
1432(equivalent to the shell variable \fBowd\fR).
1433This is not a substitution at all, but an abbreviation recognized by only
1434those commands.  Nonetheless, it too can be prevented by quoting.
1435.SS Commands
1436The next three sections describe how the shell executes commands and
1437deals with their input and output.
1438.SS Simple commands, pipelines and sequences
1439A simple command is a sequence of words, the first of which specifies the
1440command to be executed.  A series of simple commands joined by `|' characters
1441forms a pipeline.  The output of each command in a pipeline is connected to the
1442input of the next.
1443.PP
1444Simple commands and pipelines may be joined into sequences with `;', and will
1445be executed sequentially.  Commands and pipelines can also be joined into
1446sequences with `||' or `&&', indicating, as in the C language, that the second
1447is to be executed only if the first fails or succeeds respectively.
1448.PP
1449A simple command, pipeline or sequence may be placed in parentheses, `()',
1450to form a simple command, which may in turn be a component of a pipeline or
1451sequence.  A command, pipeline or sequence can be executed
1452without waiting for it to terminate by following it with an `&'.
1453.SS "Builtin and non-builtin command execution"
1454Builtin commands are executed within the shell.  If any component of a
1455pipeline except the last is a builtin command, the pipeline is executed
1456in a subshell.
1457.PP
1458Parenthesized commands are always executed in a subshell.
1459.IP "" 4
1460(cd; pwd); pwd
1461.PP
1462thus prints the \fBhome\fR directory, leaving you where you were
1463(printing this after the home directory), while
1464.IP "" 4
1465cd; pwd
1466.PP
1467leaves you in the \fBhome\fR directory.  Parenthesized commands are most often
1468used to prevent \fIcd\fR from affecting the current shell.
1469.PP
1470When a command to be executed is found not to be a builtin command the shell
1471attempts to execute the command via \fIexecve\fR(2).  Each word in the variable
1472\fBpath\fR names a directory in which the shell will look for the
1473command.  If it is given neither a \fB\-c\fR nor a \fB\-t\fR option, the shell
1474hashes the names in these directories into an internal table so that it will
1475try an \fIexecve\fR(2) in only a directory where there is a possibility that the
1476command resides there.  This greatly speeds command location when a large
1477number of directories are present in the search path.  If this mechanism has
1478been turned off (via \fIunhash\fR), if the shell was given a \fB\-c\fR or
1479\fB\-t\fR argument or in any case for each directory component of \fBpath\fR
1480which does not begin with a `/', the shell concatenates the current working
1481directory with the given command name to form a path name of a file which it
1482then attempts to execute.
1483.PP
1484If the file has execute permissions but is not an executable to the system
1485(i.e., it is neither an executable binary nor a script that specifies its
1486interpreter), then it is assumed to be a file containing shell commands and
1487a new shell is spawned to read it.  The \fIshell\fR special alias may be set
1488to specify an interpreter other than the shell itself.
1489.PP
1490On systems which do not understand the `#!' script interpreter convention
1491the shell may be compiled to emulate it; see the \fBversion\fR shell
1492variable\fR.  If so, the shell checks the first line of the file to
1493see if it is of the form `#!\fIinterpreter\fR \fIarg\fR ...'.  If it is,
1494the shell starts \fIinterpreter\fR with the given \fIarg\fRs and feeds the
1495file to it on standard input.
1496.SS Input/output
1497The standard input and standard output of a command may be redirected with the
1498following syntax:
1499.PP
1500.PD 0
1501.TP 8
1502< \fIname
1503Open file \fIname\fR (which is first variable, command and filename
1504expanded) as the standard input.
1505.TP 8
1506<< \fIword
1507Read the shell input up to a line which is identical to \fIword\fR.  \fIword\fR
1508is not subjected to variable, filename or command substitution, and each input
1509line is compared to \fIword\fR before any substitutions are done on this input
1510line.  Unless a quoting `\e', `"', `' or ``' appears in \fIword\fR variable and
1511command substitution is performed on the intervening lines, allowing `\e' to
1512quote `$', `\e' and ``'.  Commands which are substituted have all blanks, tabs,
1513and newlines preserved, except for the final newline which is dropped.  The
1514resultant text is placed in an anonymous temporary file which is given to the
1515command as standard input.
1516.PP
1517> \fIname
1518.br
1519>! \fIname
1520.br
1521>& \fIname
1522.TP 8
1523>&! \fIname
1524The file \fIname\fR is used as standard output.  If the file does not exist
1525then it is created; if the file exists, it is truncated, its previous contents
1526being lost.
1527.RS +8
1528.PD
1529.PP
1530If the shell variable \fBnoclobber\fR is set, then the file must not exist or be a
1531character special file (e.g., a terminal or `/dev/null') or an error results.
1532This helps prevent accidental destruction of files.  In this case the `!' forms
1533can be used to suppress this check.
1534.PP
1535The forms involving `&' route the diagnostic output into the specified file as
1536well as the standard output.  \fIname\fR is expanded in the same way as `<'
1537input filenames are.
1538.PD 0
1539.RE
1540.PP
1541>> \fIname
1542.br
1543>>& \fIname
1544.br
1545>>! \fIname
1546.TP 8
1547>>&! \fIname
1548Like `>', but appends output to the end of \fIname\fR.
1549If the shell variable \fBnoclobber\fR is set, then it is an error for
1550the file \fInot\fR to exist, unless one of the `!' forms is given.
1551.PD
1552.PP
1553A command receives the environment in which the shell was invoked as modified
1554by the input-output parameters and the presence of the command in a pipeline.
1555Thus, unlike some previous shells, commands run from a file of shell commands
1556have no access to the text of the commands by default; rather they receive the
1557original standard input of the shell.  The `<<' mechanism should be used to
1558present inline data.  This permits shell command scripts to function as
1559components of pipelines and allows the shell to block read its input.  Note
1560that the default standard input for a command run detached is \fInot\fR
1561the empty file \fI/dev/null\fR, but the original standard input of the shell.
1562If this is a terminal and if the process attempts to read from the terminal,
1563then the process will block and the user will be notified (see \fBJobs\fR).
1564.PP
1565Diagnostic output may be directed through a pipe with the standard output.
1566Simply use the form `|&' rather than just `|'.
1567.PP
1568The shell cannot presently redirect diagnostic output without also redirecting
1569standard output, but `(\fIcommand\fR > \fIoutput-file\fR) >& \fIerror-file\fR'
1570is often an acceptable workaround.  Either \fIoutput-file\fR or
1571\fIerror-file\fR may be `/dev/tty' to send output to the terminal.
1572.SS Features
1573Having described how the shell accepts, parses and executes
1574command lines, we now turn to a variety of its useful features.
1575.SS "Control flow"
1576The shell contains a number of commands which can be used to regulate the
1577flow of control in command files (shell scripts) and (in limited but
1578useful ways) from terminal input.  These commands all operate by forcing the
1579shell to reread or skip in its input and, due to the implementation,
1580restrict the placement of some of the commands.
1581.PP
1582The \fIforeach\fR, \fIswitch\fR, and \fIwhile\fR statements, as well as the
1583\fIif-then-else\fR form of the \fIif\fR statement, require that the major
1584keywords appear in a single simple command on an input line as shown below.
1585.PP
1586If the shell's input is not seekable, the shell buffers up input whenever
1587a loop is being read and performs seeks in this internal buffer to
1588accomplish the rereading implied by the loop.  (To the extent that this
1589allows, backward \fIgoto\fRs will succeed on non-seekable inputs.)
1590.SS Expressions
1591The \fIif\fR, \fIwhile\fR and \fIexit\fR builtin commands
1592use expressions with a common syntax.  The expressions can include any
1593of the operators described in the next three sections.  Note that the \fI@\fR
1594builtin command (q.v.) has its own separate syntax.
1595.SS "Logical, arithmetical and comparison operators"
1596These operators are similar to those of C and have the same precedence.
1597They include
1598.IP "" 4
1599||  &&  |  ^  &  ==  !=  =~  !~  <=  >=
1600.br
1601<  > <<  >>  +  \-  *  /  %  !  ~  (  )
1602.PP
1603Here the precedence increases to the right, `==' `!=' `=~' and `!~', `<='
1604`>=' `<' and `>', `<<' and `>>', `+' and `\-', `*' `/' and `%' being, in
1605groups, at the same level.  The `==' `!=' `=~' and `!~' operators compare
1606their arguments as strings; all others operate on numbers.  The operators
1607`=~' and `!~' are like `!=' and `==' except that the right hand side is a
1608glob-pattern (see \fBFilename substitution\fR) against which the left hand
1609operand is matched.  This reduces the need for use of the \fIswitch\fR
1610builtin command in shell scripts when all that is really needed is
1611pattern matching.
1612.PP
1613Strings which begin with `0' are considered octal numbers.  Null or
1614missing arguments are considered `0'.  The results of all expressions are
1615strings, which represent decimal numbers.  It is important to note that
1616no two components of an expression can appear in the same word; except
1617when adjacent to components of expressions which are syntactically
1618significant to the parser (`&' `|' `<' `>' `(' `)') they should be
1619surrounded by spaces.
1620.SS "Command exit status"
1621Commands can be executed in expressions and their exit status
1622returned by enclosing them in braces (`{}').  Remember that the braces should
1623be separated from the words of the command by spaces.  Command executions
1624succeed, returning true, i.e., `1', if the command exits with status 0,
1625otherwise they fail, returning false, i.e., `0'.  If more detailed status
1626information is required then the command should be executed outside of an
1627expression and the \fBstatus\fR shell variable examined.
1628.SS "File inquiry operators"
1629Some of these operators perform true/false tests on files and related
1630objects.  They are of the form \fB\-\fIop file\fR, where \fIop\fR is one of
1631.PP
1632.PD 0
1633.RS +4
1634.TP 4
1635.B r
1636Read access
1637.TP 4
1638.B w
1639Write access
1640.TP 4
1641.B x
1642Execute access
1643.TP 4
1644.B X
1645Executable in the path or shell builtin, e.g., `\-X ls' and `\-X ls\-F' are
1646generally true, but `\-X /bin/ls' is not (+)
1647.TP 4
1648.B e
1649Existence
1650.TP 4
1651.B o
1652Ownership
1653.TP 4
1654.B z
1655Zero size
1656.TP 4
1657.B s
1658Non-zero size (+)
1659.TP 4
1660.B f
1661Plain file
1662.TP 4
1663.B d
1664Directory
1665.TP 4
1666.B l
1667Symbolic link (+) *
1668.TP 4
1669.B b
1670Block special file (+)
1671.TP 4
1672.B c
1673Character special file (+)
1674.TP 4
1675.B p
1676Named pipe (fifo) (+) *
1677.TP 4
1678.B S
1679Socket special file (+) *
1680.TP 4
1681.B u
1682Set-user-ID bit is set (+)
1683.TP 4
1684.B g
1685Set-group-ID bit is set (+)
1686.TP 4
1687.B k
1688Sticky bit is set (+)
1689.TP 4
1690.B t
1691\fIfile\fR (which must be a digit) is an open file descriptor
1692for a terminal device (+)
1693.TP 4
1694.B R
1695Has been migrated (convex only) (+)
1696.TP 4
1697.B L
1698Applies subsequent operators in a multiple-operator test to a symbolic link
1699rather than to the file to which the link points (+) *
1700.RE
1701.PD
1702.PP
1703\fIfile\fR is command and filename expanded and then tested to
1704see if it has the specified relationship to the real user.  If \fIfile\fR
1705does not exist or is inaccessible or, for the operators indicated by `*',
1706if the specified file type does not exist on the current system,
1707then all enquiries return false, i.e., `0'.
1708.PP
1709These operators may be combined for conciseness: `\-\fIxy file\fR' is
1710equivalent to `\-\fIx file\fR && \-\fIy file\fR'.  (+) For example, `\-fx' is true
1711(returns `1') for plain executable files, but not for directories.
1712.PP
1713\fBL\fR may be used in a multiple-operator test to apply subsequent operators
1714to a symbolic link rather than to the file to which the link points.
1715For example, `\-lLo' is true for links owned by the invoking user.
1716\fBLr\fR, \fBLw\fR and \fBLx\fR are always true for links and false for
1717non-links.  \fBL\fR has a different meaning when it is the last operator
1718in a multiple-operator test; see below.
1719.PP
1720It is possible but not useful, and sometimes misleading, to combine operators
1721which expect \fIfile\fR to be a file with operators which do not,
1722(e.g., \fBX\fR and \fBt\fR).  Following \fBL\fR with a non-file operator
1723can lead to particularly strange results.
1724.PP
1725Other operators return other information, i.e., not just `0' or `1'.  (+)
1726They have the same format as before; \fIop\fR may be one of
1727.PP
1728.PD 0
1729.RS +4
1730.TP 8
1731.B A
1732Last file access time, as the number of seconds since the epoch
1733.TP 8
1734.B A:
1735Like \fBA\fR, but in timestamp format, e.g., `Fri May 14 16:36:10 1993'
1736.TP 8
1737.B M
1738Last file modification time
1739.TP 8
1740.B M:
1741Like \fBM\fR, but in timestamp format
1742.TP 8
1743.B C
1744Last inode modification time
1745.TP 8
1746.B C:
1747Like \fBC\fR, but in timestamp format
1748.TP 8
1749.B D
1750Device number
1751.TP 8
1752.B I
1753Inode number
1754.TP 8
1755.B F
1756Composite \fBf\fRile identifier, in the form \fIdevice\fR:\fIinode\fR
1757.TP 8
1758.B L
1759The name of the file pointed to by a symbolic link
1760.TP 8
1761.B N
1762Number of (hard) links
1763.TP 8
1764.B P
1765Permissions, in octal, without leading zero
1766.TP 8
1767.B P:
1768Like \fBP\fR, with leading zero
1769.TP 8
1770.B P\fImode
1771Equivalent to `\-P \fIfile\fR & \fImode\fR', e.g., `\-P22 \fIfile\fR' returns
1772`22' if \fIfile\fR is writable by group and other, `20' if by group only,
1773and `0' if by neither
1774.TP 8
1775.B P\fImode\fB:
1776Like \fBP\fImode\fB:\fR, with leading zero
1777.TP 8
1778.B U
1779Numeric userid
1780.TP 8
1781.B U:
1782Username, or the numeric userid if the username is unknown
1783.TP 8
1784.B G
1785Numeric groupid
1786.TP 8
1787.B G:
1788Groupname, or the numeric groupid if the groupname is unknown
1789.TP 8
1790.B Z
1791Size, in bytes
1792.RE
1793.PD
1794.PP
1795Only one of these operators may appear in a multiple-operator test, and it
1796must be the last.  Note that \fBL\fR has a different meaning at the end of and
1797elsewhere in a multiple-operator test.  Because `0' is a valid return value
1798for many of these operators, they do not return `0' when they fail: most
1799return `\-1', and \fBF\fR returns `:'.
1800.PP
1801If the shell is compiled with POSIX defined (see the \fBversion\fR shell
1802variable), the result of a file inquiry is based on the permission bits of
1803the file and not on the result of the \fIaccess\fR(2) system call.
1804For example, if one tests a file with \fB\-w\fR whose permissions would
1805ordinarily allow writing but which is on a file system mounted read-only,
1806the test will succeed in a POSIX shell but fail in a non-POSIX shell.
1807.PP
1808File inquiry operators can also be evaluated with the \fIfiletest\fR builtin
1809command (q.v.) (+).
1810.SS Jobs
1811The shell associates a \fIjob\fR with each pipeline.  It keeps a table of
1812current jobs, printed by the \fIjobs\fR command, and assigns them small integer
1813numbers.  When a job is started asynchronously with `&', the shell prints a
1814line which looks like
1815.IP "" 4
1816[1] 1234
1817.PP
1818indicating that the job which was started asynchronously was job number 1 and
1819had one (top-level) process, whose process id was 1234.
1820.PP
1821If you are running a job and wish to do something else you may hit the suspend
1822key (usually `^Z'),
1823which sends a STOP signal to the current job.  The shell will then normally
1824indicate that the job has been `Suspended' and print another prompt.
1825If the \fBlistjobs\fR shell variable is set, all jobs will be listed
1826like the \fIjobs\fR builtin command; if it is set to `long' the listing will
1827be in long format, like `jobs \-l'.
1828You can then manipulate the state of the suspended job.
1829You can put it in the
1830``background'' with the \fIbg\fR command or run some other commands and
1831eventually bring the job back into the ``foreground'' with \fIfg\fR.
1832(See also the \fIrun-fg-editor\fR editor command.)
1833A `^Z' takes effect immediately and is like an interrupt
1834in that pending output and unread input are discarded when it is typed.
1835The \fIwait\fR builtin command causes the shell to wait for all background
1836jobs to complete.
1837.PP
1838The `^]' key sends a delayed suspend signal, which does not generate a STOP
1839signal until a program attempts to \fIread\fR(2) it, to the current job.
1840This can usefully be typed ahead when you have prepared some commands for a
1841job which you wish to stop after it has read them.
1842The `^Y' key performs this function in \fIcsh\fR(1); in \fItcsh\fR,
1843`^Y' is an editing command.  (+)
1844.PP
1845A job being run in the background stops if it tries to read from the
1846terminal.  Background jobs are normally allowed to produce output, but this can
1847be disabled by giving the command `stty tostop'.  If you set this tty option,
1848then background jobs will stop when they try to produce output like they do
1849when they try to read input.
1850.PP
1851There are several ways to refer to jobs in the shell.  The character `%'
1852introduces a job name.  If you wish to refer to job number 1, you can name it
1853as `%1'.  Just naming a job brings it to the foreground; thus `%1' is a synonym
1854for `fg %1', bringing job 1 back into the foreground.  Similarly, saying `%1 &'
1855resumes job 1 in the background, just like `bg %1'.  A job can also be named
1856by an unambiguous prefix of the string typed in to start it: `%ex' would
1857normally restart a suspended \fIex\fR(1) job, if there were only one suspended
1858job whose name began with the string `ex'.  It is also possible to say
1859`%?\fIstring\fR' to specify a job whose text contains \fIstring\fR, if there
1860is only one such job.
1861.PP
1862The shell maintains a notion of the current and previous jobs.  In output
1863pertaining to jobs, the current job is marked with a `+' and the previous job
1864with a `\-'.  The abbreviations `%+', `%', and (by analogy with the syntax of
1865the \fIhistory\fR mechanism) `%%' all refer to the current job, and `%\-' refers
1866to the previous job.
1867.PP
1868The job control mechanism requires that the \fIstty\fR(1) option `new' be set
1869on some systems.  It is an artifact from a `new' implementation of the tty
1870driver which allows generation of interrupt characters from the keyboard to
1871tell jobs to stop.  See \fIstty\fR(1) and the \fIsetty\fR builtin command for
1872details on setting options in the new tty driver.
1873.SS "Status reporting"
1874The shell learns immediately whenever a process changes state.  It normally
1875informs you whenever a job becomes blocked so that no further progress is
1876possible, but only right before it prints a prompt.  This is done so that it
1877does not otherwise disturb your work.  If, however, you set the shell variable
1878\fBnotify\fR, the shell will notify you immediately of changes of status in
1879background jobs.  There is also a shell command \fInotify\fR which marks a
1880single process so that its status changes will be immediately reported.  By
1881default \fInotify\fR marks the current process; simply say `notify' after
1882starting a background job to mark it.
1883.PP
1884When you try to leave the shell while jobs are stopped, you will be
1885warned that `You have stopped jobs.' You may use the \fIjobs\fR command to see
1886what they are.  If you do this or immediately try to exit again, the shell will
1887not warn you a second time, and the suspended jobs will be terminated.
1888.SS "Automatic, periodic and timed events (+)"
1889There are various ways to run commands and take other actions automatically
1890at various times in the ``life cycle'' of the shell.  They are summarized here,
1891and described in detail under the appropriate \fBBuiltin commands\fR,
1892\fBSpecial shell variables\fR and \fBSpecial aliases\fR.
1893.PP
1894The \fIsched\fR builtin command puts commands in a scheduled-event list,
1895to be executed by the shell at a given time.
1896.PP
1897The \fIbeepcmd\fR, \fIcwdcmd\fR, \fIperiodic\fR, \fIprecmd\fR, \fIpostcmd\fR,
1898and \fIjobcmd\fR
1899\fBSpecial aliases\fR can be set, respectively, to execute commands when the shell wants
1900to ring the bell, when the working directory changes, every \fBtperiod\fR
1901minutes, before each prompt, before each command gets executed, after each
1902command gets executed, and when a job is started or is brought into the
1903foreground.
1904.PP
1905The \fBautologout\fR shell variable can be set to log out or lock the shell
1906after a given number of minutes of inactivity.
1907.PP
1908The \fBmail\fR shell variable can be set to check for new mail periodically.
1909.PP
1910The \fBprintexitvalue\fR shell variable can be set to print the exit status
1911of commands which exit with a status other than zero.
1912.PP
1913The \fBrmstar\fR shell variable can be set to ask the user, when `rm *' is
1914typed, if that is really what was meant.
1915.PP
1916The \fBtime\fR shell variable can be set to execute the \fItime\fR builtin
1917command after the completion of any process that takes more than a given
1918number of CPU seconds.
1919.PP
1920The \fBwatch\fR and \fBwho\fR shell variables can be set to report when
1921selected users log in or out, and the \fIlog\fR builtin command reports
1922on those users at any time.
1923.SS "Native Language System support (+)"
1924The shell is eight bit clean
1925(if so compiled; see the \fBversion\fR shell variable)
1926and thus supports character sets needing this capability.
1927NLS support differs depending on whether or not
1928the shell was compiled to use the system's NLS (again, see \fBversion\fR).
1929In either case, 7-bit ASCII is the default character code
1930(e.g., the classification of which characters are printable) and sorting,
1931and changing the \fBLANG\fR or \fBLC_CTYPE\fR environment variables
1932causes a check for possible changes in these respects.
1933.PP
1934When using the system's NLS, the \fIsetlocale\fR(3) function is called
1935to determine appropriate character code/classification and sorting
1936(e.g., a 'en_CA.UTF-8' would yield "UTF-8" as a character code).
1937This function typically examines the \fBLANG\fR and \fBLC_CTYPE\fR
1938environment variables; refer to the system documentation for further details.
1939When not using the system's NLS, the shell simulates it by assuming that the
1940ISO 8859-1 character set is used
1941whenever either of the \fBLANG\fR and \fBLC_CTYPE\fR variables are set, regardless of
1942their values.  Sorting is not affected for the simulated NLS.
1943.PP
1944In addition, with both real and simulated NLS, all printable
1945characters in the range \e200\-\e377, i.e., those that have
1946M-\fIchar\fR bindings, are automatically rebound to \fIself-insert-command\fR.
1947The corresponding binding for the escape-\fIchar\fR sequence, if any, is
1948left alone.
1949These characters are not rebound if the \fBNOREBIND\fR environment variable
1950is set.  This may be useful for the simulated NLS or a primitive real NLS
1951which assumes full ISO 8859-1.  Otherwise, all M-\fIchar\fR bindings in the
1952range \e240\-\e377 are effectively undone.
1953Explicitly rebinding the relevant keys with \fIbindkey\fR
1954is of course still possible.
1955.PP
1956Unknown characters (i.e., those that are neither printable nor control
1957characters) are printed in the format \ennn.
1958If the tty is not in 8 bit mode, other 8 bit characters are printed by
1959converting them to ASCII and using standout mode.  The shell
1960never changes the 7/8 bit mode of the tty and tracks user-initiated
1961changes of 7/8 bit mode.  NLS users (or, for that matter, those who want to
1962use a meta key) may need to explicitly set
1963the tty in 8 bit mode through the appropriate \fIstty\fR(1)
1964command in, e.g., the \fI~/.login\fR file.
1965.SS "OS variant support (+)"
1966A number of new builtin commands are provided to support features in
1967particular operating systems.  All are described in detail in the
1968\fBBuiltin commands\fR section.
1969.PP
1970On systems that support TCF (aix-ibm370, aix-ps2),
1971\fIgetspath\fR and \fIsetspath\fR get and set the system execution path,
1972\fIgetxvers\fR and \fIsetxvers\fR get and set the experimental version prefix
1973and \fImigrate\fR migrates processes between sites.  The \fIjobs\fR builtin
1974prints the site on which each job is executing.
1975.PP
1976Under BS2000, \fIbs2cmd\fR executes commands of the underlying BS2000/OSD
1977operating system.
1978.PP
1979Under Domain/OS, \fIinlib\fR adds shared libraries to the current environment,
1980\fIrootnode\fR changes the rootnode and \fIver\fR changes the systype.
1981.PP
1982Under Mach, \fIsetpath\fR is equivalent to Mach's \fIsetpath\fR(1).
1983.PP
1984Under Masscomp/RTU and Harris CX/UX, \fIuniverse\fR sets the universe.
1985.PP
1986Under Harris CX/UX, \fIucb\fR or \fIatt\fR runs a command under the specified
1987universe.
1988.PP
1989Under Convex/OS, \fIwarp\fR prints or sets the universe.
1990.PP
1991The \fBVENDOR\fR, \fBOSTYPE\fR and \fBMACHTYPE\fR environment variables
1992indicate respectively the vendor, operating system and machine type
1993(microprocessor class or machine model) of the
1994system on which the shell thinks it is running.
1995These are particularly useful when sharing one's home directory between several
1996types of machines; one can, for example,
1997.IP "" 4
1998set path = (~/bin.$MACHTYPE /usr/ucb /bin /usr/bin .)
1999.PP
2000in one's \fI~/.login\fR and put executables compiled for each machine in the
2001appropriate directory.
2002.PP
2003The \fBversion\fR shell
2004variable indicates what options were chosen when the shell was compiled.
2005.PP
2006Note also the \fInewgrp\fR builtin, the \fBafsuser\fR and
2007\fBecho_style\fR shell variables and the system-dependent locations of
2008the shell's input files (see \fBFILES\fR).
2009.SS "Signal handling"
2010Login shells ignore interrupts when reading the file \fI~/.logout\fR.
2011The shell ignores quit signals unless started with \fB\-q\fR.
2012Login shells catch the terminate signal, but non-login shells inherit the
2013terminate behavior from their parents.
2014Other signals have the values which the shell inherited from its parent.
2015.PP
2016In shell scripts, the shell's handling of interrupt and terminate signals
2017can be controlled with \fIonintr\fR, and its handling of hangups can be
2018controlled with \fIhup\fR and \fInohup\fR.
2019.PP
2020The shell exits on a hangup (see also the \fBlogout\fR shell variable).  By
2021default, the shell's children do too, but the shell does not send them a
2022hangup when it exits.  \fIhup\fR arranges for the shell to send a hangup to
2023a child when it exits, and \fInohup\fR sets a child to ignore hangups.
2024.SS "Terminal management (+)"
2025The shell uses three different sets of terminal (``tty'') modes:
2026`edit', used when editing, `quote', used when quoting literal characters,
2027and `execute', used when executing commands.
2028The shell holds some settings in each mode constant, so commands which leave
2029the tty in a confused state do not interfere with the shell.
2030The shell also matches changes in the speed and padding of the tty.
2031The list of tty modes that are kept constant
2032can be examined and modified with the \fIsetty\fR builtin.
2033Note that although the editor uses CBREAK mode (or its equivalent),
2034it takes typed-ahead characters anyway.
2035.PP
2036The \fIechotc\fR, \fIsettc\fR and \fItelltc\fR commands can be used to
2037manipulate and debug terminal capabilities from the command line.
2038.PP
2039On systems that support SIGWINCH or SIGWINDOW, the shell
2040adapts to window resizing automatically and adjusts the environment
2041variables \fBLINES\fR and \fBCOLUMNS\fR if set.  If the environment
2042variable \fBTERMCAP\fR contains li# and co# fields, the shell adjusts
2043them to reflect the new window size.
2044.SH REFERENCE
2045The next sections of this manual describe all of the available
2046\fBBuiltin commands\fR, \fBSpecial aliases\fR and
2047\fBSpecial shell variables\fR.
2048.SS "Builtin commands"
2049.TP 8
2050.B %\fIjob
2051A synonym for the \fIfg\fR builtin command.
2052.TP 8
2053.B %\fIjob \fB&
2054A synonym for the \fIbg\fR builtin command.
2055.TP 8
2056.B :
2057Does nothing, successfully.
2058.PP
2059.B @
2060.br
2061.B @ \fIname\fB = \fIexpr
2062.br
2063.B @ \fIname\fR[\fIindex\fR]\fB = \fIexpr
2064.br
2065.B @ \fIname\fB++\fR|\fB--
2066.PD 0
2067.TP 8
2068.B @ \fIname\fR[\fIindex\fR]\fB++\fR|\fB--
2069The first form prints the values of all shell variables.
2070.PD
2071.RS +8
2072.PP
2073The second form assigns the value of \fIexpr\fR to \fIname\fR.
2074The third form assigns the value of \fIexpr\fR to the \fIindex\fR'th
2075component of \fIname\fR; both \fIname\fR and its \fIindex\fR'th component
2076must already exist.
2077.PP
2078\fIexpr\fR may contain the operators `*', `+', etc., as in C.
2079If \fIexpr\fR contains `<', `>', `&' or `' then at least that part of
2080\fIexpr\fR must be placed within `()'.
2081Note that the syntax of \fIexpr\fR has nothing to do with that described
2082under \fBExpressions\fR.
2083.PP
2084The fourth and fifth forms increment (`++') or decrement (`\-\-') \fIname\fR
2085or its \fIindex\fR'th component.
2086.PP
2087The space between `@' and \fIname\fR is required.  The spaces between
2088\fIname\fR and `=' and between `=' and \fIexpr\fR are optional.  Components of
2089\fIexpr\fR must be separated by spaces.
2090.RE
2091.PD
2092.TP 8
2093.B alias \fR[\fIname \fR[\fIwordlist\fR]]
2094Without arguments, prints all aliases.
2095With \fIname\fR, prints the alias for name.
2096With \fIname\fR and \fIwordlist\fR, assigns
2097\fIwordlist\fR as the alias of \fIname\fR.
2098\fIwordlist\fR is command and filename substituted.
2099\fIname\fR may not be `alias' or `unalias'.
2100See also the \fIunalias\fR builtin command.
2101.TP 8
2102.B alloc
2103Shows the amount of dynamic memory acquired, broken down into used and free
2104memory.  With an argument shows the number of free and used blocks in each size
2105category.  The categories start at size 8 and double at each step.  This
2106command's output may vary across system types, because systems other than the VAX
2107may use a different memory allocator.
2108.TP 8
2109.B bg \fR[\fB%\fIjob\fR ...]
2110Puts the specified jobs (or, without arguments, the current job)
2111into the background, continuing each if it is stopped.
2112\fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
2113under \fBJobs\fR.
2114.PP
2115.B bindkey \fR[\fB\-l\fR|\fB\-d\fR|\fB\-e\fR|\fB\-v\fR|\fB\-u\fR] (+)
2116.br
2117\fBbindkey \fR[\fB\-a\fR] [\fB\-b\fR] [\fB\-k\fR] [\fB\-r\fR] [\fB\-\-\fR] \fIkey \fR(+)
2118.PD 0
2119.TP 8
2120\fBbindkey \fR[\fB\-a\fR] [\fB\-b\fR] [\fB\-k\fR] [\fB\-c\fR|\fB\-s\fR] [\fB\-\-\fR] \fIkey command \fR(+)
2121.\" .B macro can't take too many words, so I used \fB in the previous tags
2122Without options, the first form lists all bound keys and the editor command to which each is bound,
2123the second form lists the editor command to which \fIkey\fR is bound and
2124the third form binds the editor command \fIcommand\fR to \fIkey\fR.
2125Options include:
2126.PD
2127.PP
2128.PD 0
2129.RS +8
2130.TP 4
2131.B \-l
2132Lists all editor commands and a short description of each.
2133.TP 4
2134.B \-d
2135Binds all keys to the standard bindings for the default editor.
2136.TP 4
2137.B \-e
2138Binds all keys to the standard GNU Emacs-like bindings.
2139.TP 4
2140.B \-v
2141Binds all keys to the standard \fIvi\fR(1)-like bindings.
2142.TP 4
2143.B \-a
2144Lists or changes key-bindings in the alternative key map.
2145This is the key map used in \fIvi\fR command mode.
2146.TP 4
2147.B \-b
2148\fIkey\fR is interpreted as
2149a control character written ^\fIcharacter\fR (e.g., `^A') or
2150C-\fIcharacter\fR (e.g., `C-A'),
2151a meta character written M-\fIcharacter\fR (e.g., `M-A'),
2152a function key written F-\fIstring\fR (e.g., `F-string'),
2153or an extended prefix key written X-\fIcharacter\fR (e.g., `X-A').
2154.TP 4
2155.B \-k
2156\fIkey\fR is interpreted as a symbolic arrow key name, which may be one of
2157`down', `up', `left' or `right'.
2158.TP 4
2159.B \-r
2160Removes \fIkey\fR's binding.
2161Be careful: `bindkey \-r' does \fInot\fR bind \fIkey\fR to
2162\fIself-insert-command\fR (q.v.), it unbinds \fIkey\fR completely.
2163.TP 4
2164.B \-c
2165\fIcommand\fR is interpreted as a builtin or external command instead of an
2166editor command.
2167.TP 4
2168.B \-s
2169\fIcommand\fR is taken as a literal string and treated as terminal input
2170when \fIkey\fR is typed.  Bound keys in \fIcommand\fR are themselves
2171reinterpreted, and this continues for ten levels of interpretation.
2172.TP 4
2173.B \-\-
2174Forces a break from option processing, so the next word is taken as \fIkey\fR
2175even if it begins with '\-'.
2176.TP 4
2177.B \-u \fR(or any invalid option)
2178Prints a usage message.
2179.PD
2180.PP
2181\fIkey\fR may be a single character or a string.
2182If a command is bound to a string, the first character of the string is bound to
2183\fIsequence-lead-in\fR and the entire string is bound to the command.
2184.PP
2185Control characters in \fIkey\fR can be literal (they can be typed by preceding
2186them with the editor command \fIquoted-insert\fR, normally bound to `^V') or
2187written caret-character style, e.g., `^A'.  Delete is written `^?'
2188(caret-question mark).  \fIkey\fR and \fIcommand\fR can contain backslashed
2189escape sequences (in the style of System V \fIecho\fR(1)) as follows:
2190.RS +4
2191.TP 8
2192.PD 0
2193.B \ea
2194Bell
2195.TP 8
2196.B \eb
2197Backspace
2198.TP 8
2199.B \ee
2200Escape
2201.TP 8
2202.B \ef
2203Form feed
2204.TP 8
2205.B \en
2206Newline
2207.TP 8
2208.B \er
2209Carriage return
2210.TP 8
2211.B \et
2212Horizontal tab
2213.TP 8
2214.B \ev
2215Vertical tab
2216.TP 8
2217.B \e\fInnn
2218The ASCII character corresponding to the octal number \fInnn\fR
2219.PD
2220.RE
2221.PP
2222`\e' nullifies the special meaning of the following character, if it has
2223any, notably `\\' and `^'.
2224.RE
2225.TP 8
2226.B bs2cmd \fIbs2000-command\fR (+)
2227Passes \fIbs2000-command\fR to the BS2000 command interpreter for
2228execution. Only non-interactive commands can be executed, and it is
2229not possible to execute any command that would overlay the image
2230of the current process, like /EXECUTE or /CALL-PROCEDURE. (BS2000 only)
2231.TP 8
2232.B break
2233Causes execution to resume after the \fIend\fR of the nearest
2234enclosing \fIforeach\fR or \fIwhile\fR.  The remaining commands on the
2235current line are executed.  Multi-level breaks are thus
2236possible by writing them all on one line.
2237.TP 8
2238.B breaksw
2239Causes a break from a \fIswitch\fR, resuming after the \fIendsw\fR.
2240.TP 8
2241.B builtins \fR(+)
2242Prints the names of all builtin commands.
2243.TP 8
2244.B bye \fR(+)
2245A synonym for the \fIlogout\fR builtin command.
2246Available only if the shell was so compiled;
2247see the \fBversion\fR shell variable.
2248.TP 8
2249.B case \fIlabel\fB:
2250A label in a \fIswitch\fR statement as discussed below.
2251.TP 8
2252.B cd \fR[\fB\-p\fR] [\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR] [\fIname\fR]
2253If a directory \fIname\fR is given, changes the shell's working directory
2254to \fIname\fR.  If not, changes to \fBhome\fR.
2255If \fIname\fR is `\-' it is interpreted as the previous working directory
2256(see \fBOther substitutions\fR).  (+)
2257If \fIname\fR is not a subdirectory of the current directory
2258(and does not begin with `/', `./' or `../'), each component of the variable
2259\fBcdpath\fR is checked to see if it has a subdirectory \fIname\fR.  Finally, if
2260all else fails but \fIname\fR is a shell variable whose value
2261begins with `/', then this is tried to see if it is a directory.
2262.RS +8
2263.PP
2264With \fB\-p\fR, prints the final directory stack, just like \fIdirs\fR.
2265The \fB\-l\fR, \fB\-n\fR and \fB\-v\fR flags have the same effect on \fIcd\fR
2266as on \fIdirs\fR, and they imply \fB\-p\fR.  (+)
2267.PP
2268See also the \fBimplicitcd\fR shell variable.
2269.RE
2270.TP 8
2271.B chdir
2272A synonym for the \fIcd\fR builtin command.
2273.TP 8
2274.B complete \fR[\fIcommand\fR [\fIword\fB/\fIpattern\fB/\fIlist\fR[\fB:\fIselect\fR]\fB/\fR[[\fIsuffix\fR]\fB/\fR] ...]] (+)
2275Without arguments, lists all completions.
2276With \fIcommand\fR, lists completions for \fIcommand\fR.
2277With \fIcommand\fR and \fIword\fR etc., defines completions.
2278.RS +8
2279.PP
2280\fIcommand\fR may be a full command name or a glob-pattern
2281(see \fBFilename substitution\fR).  It can begin with `\-' to indicate that
2282completion should be used only when \fIcommand\fR is ambiguous.
2283.PP
2284\fIword\fR specifies which word relative to the current word
2285is to be completed, and may be one of the following:
2286.PP
2287.PD 0
2288.RS +4
2289.TP 4
2290.B c
2291Current-word completion.
2292\fIpattern\fR is a glob-pattern which must match the beginning of the current word on
2293the command line.  \fIpattern\fR is ignored when completing the current word.
2294.TP 4
2295.B C
2296Like \fBc\fR, but includes \fIpattern\fR when completing the current word.
2297.TP 4
2298.B n
2299Next-word completion.
2300\fIpattern\fR is a glob-pattern which must match the beginning of the previous word on
2301the command line.
2302.TP 4
2303.B N
2304Like \fBn\fR, but must match the beginning of the word two before the current word.
2305.TP 4
2306.B p
2307Position-dependent completion.
2308\fIpattern\fR is a numeric range, with the same syntax used to index shell
2309variables, which must include the current word.
2310.PD
2311.RE
2312.PP
2313\fIlist\fR, the list of possible completions, may be one of the following:
2314.PP
2315.PD 0
2316.RS +4
2317.TP 8
2318.B a
2319Aliases
2320.TP 8
2321.B b
2322Bindings (editor commands)
2323.TP 8
2324.B c
2325Commands (builtin or external commands)
2326.TP 8
2327.B C
2328External commands which begin with the supplied path prefix
2329.TP 8
2330.B d
2331Directories
2332.TP 8
2333.B D
2334Directories which begin with the supplied path prefix
2335.TP 8
2336.B e
2337Environment variables
2338.TP 8
2339.B f
2340Filenames
2341.TP 8
2342.B F
2343Filenames which begin with the supplied path prefix
2344.TP 8
2345.B g
2346Groupnames
2347.TP 8
2348.B j
2349Jobs
2350.TP 8
2351.B l
2352Limits
2353.TP 8
2354.B n
2355Nothing
2356.TP 8
2357.B s
2358Shell variables
2359.TP 8
2360.B S
2361Signals
2362.TP 8
2363.B t
2364Plain (``text'') files
2365.TP 8
2366.B T
2367Plain (``text'') files which begin with the supplied path prefix
2368.TP 8
2369.B v
2370Any variables
2371.TP 8
2372.B u
2373Usernames
2374.TP 8
2375.B x
2376Like \fBn\fR, but prints \fIselect\fR when \fIlist-choices\fR is used.
2377.TP 8
2378.B X
2379Completions
2380.TP 8
2381$\fIvar\fR
2382Words from the variable \fIvar\fR
2383.TP 8
2384(...)
2385Words from the given list
2386.TP 8
2387`...`
2388Words from the output of command
2389.PD
2390.RE
2391.PP
2392\fIselect\fR is an optional glob-pattern.
2393If given, words from only \fIlist\fR that match \fIselect\fR are considered
2394and the \fBfignore\fR shell variable is ignored.
2395The last three types of completion may not have a \fIselect\fR
2396pattern, and \fBx\fR uses \fIselect\fR as an explanatory message when
2397the \fIlist-choices\fR editor command is used.
2398.PP
2399\fIsuffix\fR is a single character to be appended to a successful
2400completion.  If null, no character is appended.  If omitted (in which
2401case the fourth delimiter can also be omitted), a slash is appended to
2402directories and a space to other words.
2403.PP
2404Now for some examples.  Some commands take only directories as arguments,
2405so there's no point completing plain files.
2406.IP "" 4
2407> complete cd 'p/1/d/'
2408.PP
2409completes only the first word following `cd' (`p/1') with a directory.
2410\fBp\fR-type completion can also be used to narrow down command completion:
2411.IP "" 4
2412> co[^D]
2413.br
2414complete compress
2415.br
2416> complete \-co* 'p/0/(compress)/'
2417.br
2418> co[^D]
2419.br
2420> compress
2421.PP
2422This completion completes commands (words in position 0, `p/0')
2423which begin with `co' (thus matching `co*') to `compress' (the only
2424word in the list).
2425The leading `\-' indicates that this completion is to be used with only
2426ambiguous commands.
2427.IP "" 4
2428> complete find 'n/\-user/u/'
2429.PP
2430is an example of \fBn\fR-type completion.  Any word following `find' and
2431immediately following `\-user' is completed from the list of users.
2432.IP "" 4
2433> complete cc 'c/\-I/d/'
2434.PP
2435demonstrates \fBc\fR-type completion.  Any word following `cc' and beginning
2436with `\-I' is completed as a directory.  `\-I' is not taken as part of the
2437directory because we used lowercase \fBc\fR.
2438.PP
2439Different \fIlist\fRs are useful with different commands.
2440.IP "" 4
2441> complete alias 'p/1/a/'
2442.br
2443> complete man 'p/*/c/'
2444.br
2445> complete set 'p/1/s/'
2446.br
2447> complete true 'p/1/x:Truth has no options./'
2448.PP
2449These complete words following `alias' with aliases, `man' with commands,
2450and `set' with shell variables.
2451`true' doesn't have any options, so \fBx\fR does nothing when completion
2452is attempted and prints `Truth has no options.' when completion choices are listed.
2453.PP
2454Note that the \fIman\fR example, and several other examples below, could
2455just as well have used 'c/*' or 'n/*' as 'p/*'.
2456.PP
2457Words can be completed from a variable evaluated at completion time,
2458.IP "" 4
2459> complete ftp 'p/1/$hostnames/'
2460.br
2461> set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu)
2462.br
2463> ftp [^D]
2464.br
2465rtfm.mit.edu tesla.ee.cornell.edu
2466.br
2467> ftp [^C]
2468.br
2469> set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net)
2470.br
2471> ftp [^D]
2472.br
2473rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net
2474.PP
2475or from a command run at completion time:
2476.IP "" 4
2477> complete kill 'p/*/`ps | awk \\{print\\ \\$1\\}`/'
2478.br
2479> kill \-9 [^D]
2480.br
248123113 23377 23380 23406 23429 23529 23530 PID
2482.PP
2483Note that the \fIcomplete\fR command does not itself quote its arguments,
2484so the braces, space and `$' in `{print $1}' must be quoted explicitly.
2485.PP
2486One command can have multiple completions:
2487.IP "" 4
2488> complete dbx 'p/2/(core)/' 'p/*/c/'
2489.PP
2490completes the second argument to `dbx' with the word `core' and all other
2491arguments with commands.  Note that the positional completion is specified
2492before the next-word completion.
2493Because completions are evaluated from left to right, if
2494the next-word completion were specified first it would always match
2495and the positional completion would never be executed.  This is a
2496common mistake when defining a completion.
2497.PP
2498The \fIselect\fR pattern is useful when a command takes files with only
2499particular forms as arguments.  For example,
2500.IP "" 4
2501> complete cc 'p/*/f:*.[cao]/'
2502.PP
2503completes `cc' arguments to files ending in only `.c', `.a', or `.o'.
2504\fIselect\fR can also exclude files, using negation of a glob-pattern as
2505described under \fBFilename substitution\fR.  One might use
2506.IP "" 4
2507> complete rm 'p/*/f:^*.{c,h,cc,C,tex,1,man,l,y}/'
2508.PP
2509to exclude precious source code from `rm' completion.  Of course, one
2510could still type excluded names manually or override the completion
2511mechanism using the \fIcomplete-word-raw\fR or \fIlist-choices-raw\fR
2512editor commands (q.v.).
2513.PP
2514The `C', `D', `F' and `T' \fIlist\fRs are like `c', `d', `f' and `t'
2515respectively, but they use the \fIselect\fR argument in a different way: to
2516restrict completion to files beginning with a particular path prefix.  For
2517example, the Elm mail program uses `=' as an abbreviation for one's mail
2518directory.  One might use
2519.IP "" 4
2520> complete elm c@=@F:$HOME/Mail/@
2521.PP
2522to complete `elm \-f =' as if it were `elm \-f ~/Mail/'.  Note that we used `@'
2523instead of `/' to avoid confusion with the \fIselect\fR argument, and we used
2524`$HOME' instead of `~' because home directory substitution works at only the
2525beginning of a word.
2526.PP
2527\fIsuffix\fR is used to add a nonstandard suffix
2528(not space or `/' for directories) to completed words.
2529.IP "" 4
2530> complete finger 'c/*@/$hostnames/' 'p/1/u/@'
2531.PP
2532completes arguments to `finger' from the list of users, appends an `@',
2533and then completes after the `@' from the `hostnames' variable.  Note
2534again the order in which the completions are specified.
2535.PP
2536Finally, here's a complex example for inspiration:
2537.IP "" 4
2538> complete find \\
2539.br
2540\&'n/\-name/f/' 'n/\-newer/f/' 'n/\-{,n}cpio/f/' \e
2541.br
2542\'n/\-exec/c/' 'n/\-ok/c/' 'n/\-user/u/' \e
2543.br
2544\&'n/\-group/g/' 'n/\-fstype/(nfs 4.2)/' \e
2545.br
2546\&'n/\-type/(b c d f l p s)/' \e
2547.br
2548\'c/\-/(name newer cpio ncpio exec ok user \e
2549.br
2550group fstype type atime ctime depth inum \e
2551.br
2552ls mtime nogroup nouser perm print prune \e
2553.br
2554size xdev)/' \e
2555.br
2556\&'p/*/d/'
2557.PP
2558This completes words following `\-name', `\-newer', `\-cpio' or `ncpio'
2559(note the pattern which matches both) to files,
2560words following `\-exec' or `\-ok' to commands, words following `user'
2561and `group' to users and groups respectively
2562and words following `\-fstype' or `\-type' to members of the
2563given lists.  It also completes the switches themselves from the given list
2564(note the use of \fBc\fR-type completion)
2565and completes anything not otherwise completed to a directory.  Whew.
2566.PP
2567Remember that programmed completions are ignored if the word being completed
2568is a tilde substitution (beginning with `~') or a variable (beginning with `$').
2569\fIcomplete\fR is an experimental feature, and the syntax may change
2570in future versions of the shell.
2571See also the \fIuncomplete\fR builtin command.
2572.RE
2573.TP 8
2574.B continue
2575Continues execution of the nearest enclosing \fIwhile\fR or \fIforeach\fR.
2576The rest of the commands on the current line are executed.
2577.TP 8
2578.B default:
2579Labels the default case in a \fIswitch\fR statement.
2580It should come after all \fIcase\fR labels.
2581.PP
2582.B dirs \fR[\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR]
2583.br
2584.B dirs \-S\fR|\fB\-L \fR[\fIfilename\fR] (+)
2585.PD 0
2586.TP 8
2587.B dirs \-c \fR(+)
2588The first form prints the directory stack.  The top of the stack is at the
2589left and the first directory in the stack is the current directory.
2590With \fB\-l\fR, `~' or `~\fIname\fP' in the output is expanded explicitly
2591to \fBhome\fR or the pathname of the home directory for user \fIname\fP.  (+)
2592With \fB\-n\fR, entries are wrapped before they reach the edge of the screen.  (+)
2593With \fB\-v\fR, entries are printed one per line, preceded by their stack positions.  (+)
2594If more than one of \fB\-n\fR or \fB\-v\fR is given, \fB\-v\fR takes precedence.
2595\fB\-p\fR is accepted but does nothing.
2596.PD
2597.RS +8
2598.PP
2599With \fB\-S\fR, the second form saves the directory stack to \fIfilename\fR
2600as a series of \fIcd\fR and \fIpushd\fR commands.
2601With \fB\-L\fR, the shell sources \fIfilename\fR, which is presumably
2602a directory stack file saved by the \fB\-S\fR option or the \fBsavedirs\fR
2603mechanism.
2604In either case, \fBdirsfile\fR is used if \fIfilename\fR is not given and
2605\fI~/.cshdirs\fR is used if \fBdirsfile\fR is unset.
2606.PP
2607Note that login shells do the equivalent of `dirs \-L' on startup
2608and, if \fBsavedirs\fR is set, `dirs \-S' before exiting.
2609Because only \fI~/.tcshrc\fR is normally sourced before \fI~/.cshdirs\fR,
2610\fBdirsfile\fR should be set in \fI~/.tcshrc\fR rather than \fI~/.login\fR.
2611.PP
2612The last form clears the directory stack.
2613.RE
2614.TP 8
2615.B echo \fR[\fB\-n\fR] \fIword\fR ...
2616Writes each \fIword\fR to the shell's standard
2617output, separated by spaces and terminated with a newline.
2618The \fBecho_style\fR shell variable may be set to emulate (or not) the flags and escape
2619sequences of the BSD and/or System V versions of \fIecho\fR; see \fIecho\fR(1).
2620.TP 8
2621.B echotc \fR[\fB\-sv\fR] \fIarg\fR ... (+)
2622Exercises the terminal capabilities (see \fItermcap\fR(5)) in \fIargs\fR.
2623For example, 'echotc home' sends the cursor to the home position,
2624\&'echotc cm 3 10' sends it to column 3 and row 10, and
2625\&'echotc ts 0; echo "This is a test."; echotc fs' prints "This is a test."
2626in the status line.
2627.RS +8
2628.PP
2629If \fIarg\fR is 'baud', 'cols', 'lines', 'meta' or 'tabs', prints the
2630value of that capability ("yes" or "no" indicating that the terminal does
2631or does not have that capability).  One might use this to make the output
2632from a shell script less verbose on slow terminals, or limit command
2633output to the number of lines on the screen:
2634.IP "" 4
2635> set history=`echotc lines`
2636.br
2637> @ history\-\-
2638.PP
2639Termcap strings may contain wildcards which will not echo correctly.
2640One should use double quotes when setting a shell variable to a terminal
2641capability string, as in the following example that places the date in
2642the status line:
2643.IP "" 4
2644> set tosl="`echotc ts 0`"
2645.br
2646> set frsl="`echotc fs`"
2647.br
2648> echo \-n "$tosl";date; echo \-n "$frsl"
2649.PP
2650With \fB\-s\fR, nonexistent capabilities return the empty string rather
2651than causing an error.
2652With \fB\-v\fR, messages are verbose.
2653.RE
2654.PP
2655.B else
2656.br
2657.B end
2658.br
2659.B endif
2660.PD 0
2661.TP 8
2662.B endsw
2663See the description of the \fIforeach\fR, \fIif\fR, \fIswitch\fR, and
2664\fIwhile\fR statements below.
2665.PD
2666.TP 8
2667.B eval \fIarg\fR ...
2668Treats the arguments as input to the
2669shell and executes the resulting command(s) in the context
2670of the current shell.  This is usually used to execute commands
2671generated as the result of command or variable substitution,
2672because parsing occurs before these substitutions.
2673See \fItset\fR(1) for a sample use of \fIeval\fR.
2674.TP 8
2675.B exec \fIcommand\fR
2676Executes the specified command in place of the current shell.
2677.TP 8
2678.B exit \fR[\fIexpr\fR]
2679The shell exits either with the value of the specified \fIexpr\fR
2680(an expression, as described under \fBExpressions\fR)
2681or, without \fIexpr\fR, with the value of the \fBstatus\fR variable.
2682.TP 8
2683.B fg \fR[\fB%\fIjob\fR ...]
2684Brings the specified jobs (or, without arguments, the current job)
2685into the foreground, continuing each if it is stopped.
2686\fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
2687under \fBJobs\fR.
2688See also the \fIrun-fg-editor\fR editor command.
2689.TP 8
2690.B filetest \-\fIop file\fR ... (+)
2691Applies \fIop\fR (which is a file inquiry operator as described under
2692\fBFile inquiry operators\fR) to each \fIfile\fR and returns the results as a
2693space-separated list.
2694.PP
2695.B foreach \fIname \fB(\fIwordlist\fB)
2696.br
2697\&...
2698.PD 0
2699.TP 8
2700.B end
2701Successively sets the variable \fIname\fR to each member of
2702\fIwordlist\fR and executes the sequence of commands between this command
2703and the matching \fIend\fR.  (Both \fIforeach\fR and \fIend\fR
2704must appear alone on separate lines.)  The builtin command
2705\fIcontinue\fR may be used to continue the loop prematurely and
2706the builtin command \fIbreak\fR to terminate it prematurely.
2707When this command is read from the terminal, the loop is read once
2708prompting with `foreach? ' (or \fBprompt2\fR) before any statements in
2709the loop are executed.  If you make a mistake typing in a
2710loop at the terminal you can rub it out.
2711.PD
2712.TP 8
2713.B getspath \fR(+)
2714Prints the system execution path.  (TCF only)
2715.TP 8
2716.B getxvers \fR(+)
2717Prints the experimental version prefix.  (TCF only)
2718.TP 8
2719.B glob \fIwordlist
2720Like \fIecho\fR, but no `\\' escapes are recognized and words are
2721delimited by null characters in the output.  Useful for
2722programs which wish to use the shell to filename expand a list of words.
2723.TP 8
2724.B goto \fIword
2725\fIword\fR is filename and command-substituted to
2726yield a string of the form `label'.  The shell rewinds its
2727input as much as possible, searches for a line of the
2728form `label:', possibly preceded by blanks or tabs, and
2729continues execution after that line.
2730.TP 8
2731.B hashstat
2732Prints a statistics line indicating how effective the
2733internal hash table has been at locating commands (and avoiding
2734\fIexec\fR's).  An \fIexec\fR is attempted for each component of the
2735\fBpath\fR where the hash function indicates a possible hit, and
2736in each component which does not begin with a `/'.
2737.IP
2738On machines without \fIvfork\fR(2), prints only the number and size of
2739hash buckets.
2740.PP
2741.B history \fR[\fB\-hTr\fR] [\fIn\fR]
2742.br
2743.B history \-S\fR|\fB\-L|\fB\-M \fR[\fIfilename\fR] (+)
2744.PD 0
2745.TP 8
2746.B history \-c \fR(+)
2747The first form prints the history event list.
2748If \fIn\fR is given only the \fIn\fR most recent events are printed or saved.
2749With \fB\-h\fR, the history list is printed without leading numbers.  If
2750\fB-T\fR is specified, timestamps are printed also in comment form.
2751(This can be used to
2752produce files suitable for loading with 'history \-L' or 'source \-h'.)
2753With \fB\-r\fR, the order of printing is most recent
2754first rather than oldest first.
2755.PD
2756.RS +8
2757.PP
2758With \fB\-S\fR, the second form saves the history list to \fIfilename\fR.
2759If the first word of the \fBsavehist\fR shell variable is set to a
2760number, at most that many lines are saved.  If the second word of
2761\fBsavehist\fR is set to `merge', the history list is merged with the
2762existing history file instead of replacing it (if there is one) and
2763sorted by time stamp.  (+) Merging is intended for an environment like
2764the X Window System
2765with several shells in simultaneous use.  Currently it succeeds
2766only when the shells quit nicely one after another.
2767.PP
2768With \fB\-L\fR, the shell appends \fIfilename\fR, which is presumably a
2769history list saved by the \fB\-S\fR option or the \fBsavehist\fR mechanism,
2770to the history list.
2771\fB\-M\fR is like \fB\-L\fR, but the contents of \fIfilename\fR are merged
2772into the history list and sorted by timestamp.
2773In either case, \fBhistfile\fR is used if \fIfilename\fR is not given and
2774\fI~/.history\fR is used if \fBhistfile\fR is unset.
2775`history \-L' is exactly like 'source \-h' except that it does not require a
2776filename.
2777.PP
2778Note that login shells do the equivalent of `history \-L' on startup
2779and, if \fBsavehist\fR is set, `history \-S' before exiting.
2780Because only \fI~/.tcshrc\fR is normally sourced before \fI~/.history\fR,
2781\fBhistfile\fR should be set in \fI~/.tcshrc\fR rather than \fI~/.login\fR.
2782.PP
2783If \fBhistlit\fR is set, the first and second forms print and save the literal
2784(unexpanded) form of the history list.
2785.PP
2786The last form clears the history list.
2787.RE
2788.TP 8
2789.B hup \fR[\fIcommand\fR] \fR(+)
2790With \fIcommand\fR, runs \fIcommand\fR such that it will exit on a hangup
2791signal and arranges for the shell to send it a hangup signal when the shell
2792exits.
2793Note that commands may set their own response to hangups, overriding \fIhup\fR.
2794Without an argument (allowed in only a shell script), causes the shell to
2795exit on a hangup for the remainder of the script.
2796See also \fBSignal handling\fR and the \fInohup\fR builtin command.
2797.TP 8
2798.B if (\fIexpr\fB) \fIcommand
2799If \fIexpr\fR (an expression, as described under \fBExpressions\fR)
2800evaluates true, then \fIcommand\fR is executed.
2801Variable substitution on \fIcommand\fR happens early, at the same time it
2802does for the rest of the \fIif\fR command.
2803\fIcommand\fR must be a simple command, not an alias, a pipeline, a command list
2804or a parenthesized command list, but it may have arguments.
2805Input/output redirection occurs even if \fIexpr\fR is
2806false and \fIcommand\fR is thus \fInot\fR executed; this is a bug.
2807.PP
2808.B if (\fIexpr\fB) then
2809.br
2810\&...
2811.br
2812.B else if (\fIexpr2\fB) then
2813.br
2814\&...
2815.br
2816.B else
2817.br
2818\&...
2819.PD 0
2820.TP 8
2821.B endif
2822If the specified \fIexpr\fR is true then the commands to the
2823first \fIelse\fR are executed; otherwise if \fIexpr2\fR is true then
2824the commands to the second \fIelse\fR are executed, etc.  Any
2825number of \fIelse-if\fR pairs are possible; only one \fIendif\fR is
2826needed.  The \fIelse\fR part is likewise optional.  (The words
2827\fIelse\fR and \fIendif\fR must appear at the beginning of input lines;
2828the \fIif\fR must appear alone on its input line or after an
2829\fIelse\fR.)
2830.PD
2831.TP 8
2832.B inlib \fIshared-library\fR ... (+)
2833Adds each \fIshared-library\fR to the current environment.  There is no way
2834to remove a shared library.  (Domain/OS only)
2835.TP 8
2836.B jobs \fR[\fB\-l\fR]
2837Lists the active jobs.  With \fB\-l\fR, lists process
2838IDs in addition to the normal information.  On TCF systems, prints
2839the site on which each job is executing.
2840.PP
2841.PD 0
2842.TP 8
2843.B kill \fR[\fB\-s \fIsignal\fR] \fB%\fIjob\fR|\fIpid\fR ...
2844.PD 0
2845.TP 8
2846.B kill \-l
2847The first and second forms sends the specified \fIsignal\fR (or, if none
2848is given, the TERM (terminate) signal) to the specified jobs or processes.
2849\fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
2850under \fBJobs\fR.
2851Signals are either given by number or by name (as given in
2852\fI/usr/include/signal.h\fR, stripped of the prefix `SIG').
2853There is no default \fIjob\fR; saying just `kill' does not send a signal
2854to the current job.  If the signal being sent is TERM (terminate)
2855or HUP (hangup), then the job or process is sent a
2856CONT (continue) signal as well.
2857The third form lists the signal names.
2858.PD
2859.TP 8
2860.B limit \fR[\fB\-h\fR] [\fIresource\fR [\fImaximum-use\fR]]
2861Limits the consumption by the current process and each
2862process it creates to not individually exceed \fImaximum-use\fR on
2863the specified \fIresource\fR.  If no \fImaximum-use\fR is given, then
2864the current limit is printed; if no \fIresource\fR is given, then
2865all limitations are given.  If the \fB\-h\fR flag is given, the
2866hard limits are used instead of the current limits.  The
2867hard limits impose a ceiling on the values of the current
2868limits.  Only the super-user may raise the hard limits, but
2869a user may lower or raise the current limits within the legal range.
2870.RS +8
2871.PP
2872Controllable resources currently include (if supported by the OS):
2873.TP
2874\fIcputime\fR
2875the maximum number of cpu-seconds to be used by each process
2876.TP
2877\fIfilesize\fR
2878the largest single file which can be created
2879.TP
2880\fIdatasize\fR
2881the maximum growth of the data+stack region via sbrk(2) beyond
2882the end of the program text
2883.TP
2884\fIstacksize\fR
2885the maximum size of the automatically-extended stack region
2886.TP
2887\fIcoredumpsize\fR
2888the size of the largest core dump that will be created
2889.TP
2890\fImemoryuse\fR
2891the maximum amount of physical memory a process
2892may have allocated to it at a given time
2893.TP
2894\fIheapsize\fR
2895the maximum amount of memory a process
2896may allocate per \fIbrk()\fR system call
2897.TP
2898\fIdescriptors\fR or \fIopenfiles\fR
2899the maximum number of open files for this process
2900.TP
2901\fIconcurrency\fR
2902the maximum number of threads for this process
2903.TP
2904\fImemorylocked\fR
2905the maximum size which a process may lock into memory using mlock(2)
2906.TP
2907\fImaxproc\fR
2908the maximum number of simultaneous processes for this user id
2909.TP
2910\fIsbsize\fR
2911the maximum size of socket buffer usage for this user
2912.PP
2913\fImaximum-use\fR may be given as a (floating point or
2914integer) number followed by a scale factor.  For all limits
2915other than \fIcputime\fR the default scale is `k' or `kilobytes'
2916(1024 bytes); a scale factor of `m' or `megabytes' may also
2917be used.  For \fIcputime\fR the default scaling is `seconds',
2918while `m' for minutes or `h' for hours, or a time of the
2919form `mm:ss' giving minutes and seconds may be used.
2920.PP
2921For both \fIresource\fR names and scale factors, unambiguous
2922prefixes of the names suffice.
2923.RE
2924.TP 8
2925.B log \fR(+)
2926Prints the \fBwatch\fR shell variable and reports on each user indicated
2927in \fBwatch\fR who is logged in, regardless of when they last logged in.
2928See also \fIwatchlog\fR.
2929.TP 8
2930.B login
2931Terminates a login shell, replacing it with an instance of
2932\fI/bin/login.\fR This is one way to log off, included for
2933compatibility with \fIsh\fR(1).
2934.TP 8
2935.B logout
2936Terminates a login shell.  Especially useful if \fBignoreeof\fR is set.
2937.TP 8
2938.B ls\-F \fR[\-\fIswitch\fR ...] [\fIfile\fR ...] (+)
2939Lists files like `ls \-F', but much faster.  It identifies each type of
2940special file in the listing with a special character:
2941.PP
2942.RS +8
2943.PD 0
2944.TP 4
2945/
2946Directory
2947.TP 4
2948*
2949Executable
2950.TP 4
2951#
2952Block device
2953.TP 4
2954%
2955Character device
2956.TP 4
2957|
2958Named pipe (systems with named pipes only)
2959.TP 4
2960=
2961Socket (systems with sockets only)
2962.TP 4
2963@
2964Symbolic link (systems with symbolic links only)
2965.TP 4
2966+
2967Hidden directory (AIX only) or context dependent (HP/UX only)
2968.TP 4
2969:
2970Network special (HP/UX only)
2971.PD
2972.PP
2973If the \fBlistlinks\fR shell variable is set, symbolic links are identified
2974in more detail (on only systems that have them, of course):
2975.PP
2976.PD 0
2977.TP 4
2978@
2979Symbolic link to a non-directory
2980.TP 4
2981>
2982Symbolic link to a directory
2983.TP 4
2984&
2985Symbolic link to nowhere
2986.PD
2987.PP
2988\fBlistlinks\fR also slows down \fIls\-F\fR and causes partitions holding
2989files pointed to by symbolic links to be mounted.
2990.PP
2991If the \fBlistflags\fR shell variable is set to `x', `a' or `A', or any
2992combination thereof (e.g., `xA'), they are used as flags to \fIls\-F\fR,
2993making it act like `ls \-xF', `ls \-Fa', `ls \-FA' or a combination
2994(e.g., `ls \-FxA').
2995On machines where `ls \-C' is not the default, \fIls\-F\fR acts like `ls \-CF',
2996unless \fBlistflags\fR contains an `x', in which case it acts like `ls \-xF'.
2997\fIls\-F\fR passes its arguments to \fIls\fR(1) if it is given any switches,
2998so `alias ls ls\-F' generally does the right thing.
2999.PP
3000The \fBls\-F\fR builtin can list files using different colors depending on the
3001filetype or extension.  See the \fBcolor\fR \fItcsh\fR variable and the
3002\fBLS_COLORS\fR environment variable.
3003.RE
3004.PP
3005.B migrate \fR[\fB\-\fIsite\fR] \fIpid\fR|\fB%\fIjobid\fR ... (+)
3006.PD 0
3007.TP 8
3008.B migrate \-\fIsite\fR (+)
3009The first form migrates the process or job to the site specified or the
3010default site determined by the system path.
3011The second form is equivalent to `migrate \-\fIsite\fR $$': it migrates the
3012current process to the specified site.  Migrating the shell
3013itself can cause unexpected behavior, because the shell
3014does not like to lose its tty.  (TCF only)
3015.PD
3016.TP 8
3017.B newgrp \fR[\fB\-\fR] \fIgroup\fR (+)
3018Equivalent to `exec newgrp'; see \fInewgrp\fR(1).
3019Available only if the shell was so compiled;
3020see the \fBversion\fR shell variable.
3021.TP 8
3022.B nice \fR[\fB+\fInumber\fR] [\fIcommand\fR]
3023Sets the scheduling priority for the shell to \fInumber\fR, or, without
3024\fInumber\fR, to 4.  With \fIcommand\fR, runs \fIcommand\fR at the appropriate
3025priority.
3026The greater the \fInumber\fR, the less cpu
3027the process gets.  The super-user may specify negative
3028priority by using `nice \-number ...'.  Command is always
3029executed in a sub-shell, and the restrictions placed on
3030commands in simple \fIif\fR statements apply.
3031.TP 8
3032.B nohup \fR[\fIcommand\fR]
3033With \fIcommand\fR, runs \fIcommand\fR such that it will ignore hangup signals.
3034Note that commands may set their own response to hangups, overriding \fInohup\fR.
3035Without an argument (allowed in only a shell script), causes the shell to
3036ignore hangups for the remainder of the script.
3037See also \fBSignal handling\fR and the \fIhup\fR builtin command.
3038.TP 8
3039.B notify \fR[\fB%\fIjob\fR ...]
3040Causes the shell to notify the user asynchronously when the status of any
3041of the specified jobs (or, without %\fIjob\fR, the current job) changes,
3042instead of waiting until the next prompt as is usual.
3043\fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
3044under \fBJobs\fR.
3045See also the \fBnotify\fR shell variable.
3046.TP 8
3047.B onintr \fR[\fB\-\fR|\fIlabel\fR]
3048Controls the action of the shell on interrupts.  Without arguments,
3049restores the default action of the shell on interrupts,
3050which is to terminate shell scripts or to return to the
3051terminal command input level.
3052With `\-', causes all interrupts to be ignored.
3053With \fIlabel\fR, causes the shell to execute a `goto \fIlabel\fR'
3054when an interrupt is received or a child process terminates because it was
3055interrupted.
3056.IP "" 8
3057\fIonintr\fR is ignored if the shell is running detached and in system
3058startup files (see \fBFILES\fR), where interrupts are disabled anyway.
3059.TP 8
3060.B popd \fR[\fB\-p\fR] [\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR] \fR[\fB+\fIn\fR]
3061Without arguments, pops the directory stack and returns to the new top directory.
3062With a number `+\fIn\fR', discards the \fIn\fR'th entry in the stack.
3063.IP "" 8
3064Finally, all forms of \fIpopd\fR print the final directory stack,
3065just like \fIdirs\fR.  The \fBpushdsilent\fR shell variable can be set to
3066prevent this and the \fB\-p\fR flag can be given to override \fBpushdsilent\fR.
3067The \fB\-l\fR, \fB\-n\fR and \fB\-v\fR flags have the same effect on \fIpopd\fR
3068as on \fIdirs\fR.  (+)
3069.TP 8
3070.B printenv \fR[\fIname\fR] (+)
3071Prints the names and values of all environment variables or,
3072with \fIname\fR, the value of the environment variable \fIname\fR.
3073.TP 8
3074.B pushd \fR[\fB\-p\fR] [\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR] [\fIname\fR|\fB+\fIn\fR]
3075Without arguments, exchanges the top two elements of the directory stack.
3076If \fBpushdtohome\fR is set, \fIpushd\fR without arguments does `pushd ~',
3077like \fIcd\fR.  (+)
3078With \fIname\fR, pushes the current working directory onto the directory
3079stack and changes to \fIname\fR.
3080If \fIname\fR is `\-' it is interpreted as the previous working directory
3081(see \fBFilename substitution\fR).  (+)
3082If \fBdunique\fR is set, \fIpushd\fR removes any instances of \fIname\fR
3083from the stack before pushing it onto the stack.  (+)
3084With a number `+\fIn\fR', rotates the \fIn\fRth element of the
3085directory stack around to be the top element and changes to it.
3086If \fBdextract\fR is set, however, `pushd +\fIn\fR' extracts the \fIn\fRth
3087directory, pushes it onto the top of the stack and changes to it.  (+)
3088.IP "" 8
3089Finally, all forms of \fIpushd\fR print the final directory stack,
3090just like \fIdirs\fR.  The \fBpushdsilent\fR shell variable can be set to
3091prevent this and the \fB\-p\fR flag can be given to override \fBpushdsilent\fR.
3092The \fB\-l\fR, \fB\-n\fR and \fB\-v\fR flags have the same effect on \fIpushd\fR
3093as on \fIdirs\fR.  (+)
3094.TP 8
3095.B rehash
3096Causes the internal hash table of the contents of the
3097directories in the \fBpath\fR variable to be recomputed.  This is
3098needed if new commands are added to directories in \fBpath\fR
3099while you are logged in.  This should be necessary only if
3100you add commands to one of your own directories, or if a
3101systems programmer changes the contents of one of the
3102system directories.  Also flushes the cache of home directories
3103built by tilde expansion.
3104.TP 8
3105.B repeat \fIcount command
3106The specified \fIcommand\fR,
3107which is subject to the same restrictions as the \fIcommand\fR
3108in the one line \fIif\fR statement above, is executed \fIcount\fR times.
3109I/O redirections occur exactly once, even if \fIcount\fR is 0.
3110.TP 8
3111.B rootnode //\fInodename \fR(+)
3112Changes the rootnode to //\fInodename\fR, so that `/' will be interpreted
3113as `//\fInodename\fR'.  (Domain/OS only)
3114.PP
3115.B sched \fR(+)
3116.br
3117.B sched \fR[\fB+\fR]\fIhh:mm command\fR \fR(+)
3118.PD 0
3119.TP 8
3120.B sched \-\fIn\fR (+)
3121The first form prints the scheduled-event list.
3122The \fBsched\fR shell variable may be set to define the format in which
3123the scheduled-event list is printed.
3124The second form adds \fIcommand\fR to the scheduled-event list.
3125For example,
3126.PD
3127.RS +8
3128.IP "" 4
3129> sched 11:00 echo It\\'s eleven o\\'clock.
3130.PP
3131causes the shell to echo `It's eleven o'clock.' at 11 AM.
3132The time may be in 12-hour AM/PM format
3133.IP "" 4
3134> sched 5pm set prompt='[%h] It\\'s after 5; go home: >'
3135.PP
3136or may be relative to the current time:
3137.IP "" 4
3138> sched +2:15 /usr/lib/uucp/uucico \-r1 \-sother
3139.PP
3140A relative time specification may not use AM/PM format.
3141The third form removes item \fIn\fR from the event list:
3142.IP "" 4
3143> sched
3144.br
3145     1  Wed Apr  4 15:42  /usr/lib/uucp/uucico \-r1 \-sother
3146.br
3147     2  Wed Apr  4 17:00  set prompt=[%h] It's after 5; go home: >
3148.br
3149> sched \-2
3150.br
3151> sched
3152.br
3153     1  Wed Apr  4 15:42  /usr/lib/uucp/uucico \-r1 \-sother
3154.PP
3155A command in the scheduled-event list is executed just before the first
3156prompt is printed after the time when the command is scheduled.
3157It is possible to miss the exact time when the command is to be run, but
3158an overdue command will execute at the next prompt.
3159A command which comes due while the shell
3160is waiting for user input is executed immediately.
3161However, normal operation of an already-running command will not
3162be interrupted so that a scheduled-event list element may be run.
3163.PP
3164This mechanism is similar to, but not the same as, the \fIat\fR(1)
3165command on some Unix systems.
3166Its major disadvantage is that it may not run a command at exactly the
3167specified time.
3168Its major advantage is that because \fIsched\fR runs directly from
3169the shell, it has access to shell variables and other structures.
3170This provides a mechanism for changing one's working environment
3171based on the time of day.
3172.RE
3173.PP
3174.B set
3175.br
3176.B set \fIname\fR ...
3177.br
3178.B set \fIname\fR\fB=\fIword\fR ...
3179.br
3180.B set [\-r] [\-f|\-l] \fIname\fR\fB=(\fIwordlist\fB)\fR ... (+)
3181.br
3182.B set \fIname[index]\fR\fB=\fIword\fR ...
3183.br
3184.B set \-r \fR(+)
3185.br
3186.B set \-r \fIname\fR ... (+)
3187.PD 0
3188.TP 8
3189.B set \-r \fIname\fR\fB=\fIword\fR ... (+)
3190The first form of the command prints the value of all shell variables.
3191Variables which contain more than a single word print as a
3192parenthesized word list.
3193The second form sets \fIname\fR to the null string.
3194The third form sets \fIname\fR to the single \fIword\fR.
3195The fourth form sets \fIname\fR to the list of words in
3196\fIwordlist\fR.  In all cases the value is command and filename expanded.
3197If \-r is specified, the value is set read-only.  If \-f or \-l are
3198specified, set only unique words keeping their order.
3199\-f prefers the first occurrence of a word, and \-l the last.
3200The fifth form sets the \fIindex\fR'th component of name to \fIword\fR;
3201this component must already exist.
3202The sixth form lists only the names of all shell variables that are read-only.
3203The seventh form makes \fIname\fR read-only, whether or not it has a value.
3204The second form sets \fIname\fR to the null string.
3205The eighth form is the same as the third form, but
3206make \fIname\fR read-only at the same time.
3207.PD
3208.IP "" 8
3209These arguments can be repeated to set and/or make read-only multiple variables
3210in a single set command.  Note, however, that variable expansion
3211happens for all arguments before any setting occurs.  Note also that `=' can
3212be adjacent to both \fIname\fR and \fIword\fR or separated from both by
3213whitespace, but cannot be adjacent to only one or the other.
3214See also the \fIunset\fR builtin command.
3215.TP 8
3216.B setenv \fR[\fIname \fR[\fIvalue\fR]]
3217Without arguments, prints the names and values of all environment variables.
3218Given \fIname\fR, sets the environment variable \fIname\fR to \fIvalue\fR
3219or, without \fIvalue\fR, to the null string.
3220.TP 8
3221.B setpath \fIpath \fR(+)
3222Equivalent to \fIsetpath\fR(1).  (Mach only)
3223.TP 8
3224.B setspath\fR LOCAL|\fIsite\fR|\fIcpu\fR ...  (+)
3225Sets the system execution path.  (TCF only)
3226.TP 8
3227.B settc \fIcap value \fR(+)
3228Tells the shell to believe that the terminal capability \fIcap\fR
3229(as defined in \fItermcap\fR(5)) has the value \fIvalue\fR.
3230No sanity checking is done.
3231Concept terminal users may have to `settc xn no' to get proper
3232wrapping at the rightmost column.
3233.TP 8
3234.B setty \fR[\fB\-d\fR|\fB\-q\fR|\fB\-x\fR] [\fB\-a\fR] [[\fB+\fR|\fB\-\fR]\fImode\fR] (+)
3235Controls which tty modes (see \fBTerminal management\fR)
3236the shell does not allow to change.
3237\fB\-d\fR, \fB\-q\fR or \fB\-x\fR tells \fIsetty\fR to act
3238on the `edit', `quote' or `execute' set of tty modes respectively; without
3239\fB\-d\fR, \fB\-q\fR or \fB\-x\fR, `execute' is used.
3240.IP "" 8
3241Without other arguments, \fIsetty\fR lists the modes in the chosen set
3242which are fixed on (`+mode') or off (`\-mode').
3243The available modes, and thus the display, vary from system to system.
3244With \fB\-a\fR, lists all tty modes in the chosen set
3245whether or not they are fixed.
3246With \fB+\fImode\fR, \fB\-\fImode\fR or \fImode\fR, fixes \fImode\fR on or off
3247or removes control from \fImode\fR in the chosen set.
3248For example, `setty +echok echoe' fixes `echok' mode on and allows commands
3249to turn `echoe' mode on or off, both when the shell is executing commands.
3250.TP 8
3251.B setxvers\fR [\fIstring\fR] (+)
3252Set the experimental version prefix to \fIstring\fR, or removes it
3253if \fIstring\fR is omitted.  (TCF only)
3254.TP 8
3255.B shift \fR[\fIvariable\fR]
3256Without arguments, discards \fBargv\fR[1] and shifts the members of
3257\fBargv\fR to the left.  It is an error for \fBargv\fR not to be set or to have
3258less than one word as value.  With \fIvariable\fR, performs the
3259same function on \fIvariable\fR.
3260.TP 8
3261.B source \fR[\fB\-h\fR] \fIname\fR [\fIargs\fR ...]
3262The shell reads and executes commands from \fIname\fR.
3263The commands are not placed on the history list.
3264If any \fIargs\fR are given, they are placed in \fBargv\fR.  (+)
3265\fIsource\fR commands may be nested;
3266if they are nested too deeply the shell may run out of file descriptors.
3267An error in a \fIsource\fR at any level terminates all nested
3268\fIsource\fR commands.
3269With \fB\-h\fR, commands are placed on the history list instead of being
3270executed, much like `history \-L'.
3271.TP 8
3272.B stop \fB%\fIjob\fR|\fIpid\fR ...
3273Stops the specified jobs or processes which are executing in the background.
3274\fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
3275under \fBJobs\fR.
3276There is no default \fIjob\fR; saying just `stop' does not stop
3277the current job.
3278.TP 8
3279.B suspend
3280Causes the shell to stop in its tracks, much as if it had
3281been sent a stop signal with \fB^Z\fR.  This is most often used to
3282stop shells started by \fIsu\fR(1).
3283.PP
3284.B switch (\fIstring\fB)
3285.br
3286.B case \fIstr1\fB:
3287.PD 0
3288.IP "" 4
3289\&...
3290.br
3291.B breaksw
3292.PP
3293\&...
3294.PP
3295.B default:
3296.IP "" 4
3297\&...
3298.br
3299.B breaksw
3300.TP 8
3301.B endsw
3302Each case label is successively matched, against the
3303specified \fIstring\fR which is first command and filename expanded.
3304The file metacharacters `*', `?' and `[...]'  may be used
3305in the case labels, which are variable expanded.  If none
3306of the labels match before a `default' label is found, then
3307the execution begins after the default label.  Each case
3308label and the default label must appear at the beginning of
3309a line.  The command \fIbreaksw\fR causes execution to continue
3310after the \fIendsw\fR.  Otherwise control may fall through case
3311labels and default labels as in C.  If no label matches and
3312there is no default, execution continues after the \fIendsw\fR.
3313.PD
3314.TP 8
3315.B telltc \fR(+)
3316Lists the values of all terminal capabilities (see \fItermcap\fR(5)).
3317.TP 8
3318.B termname \fR[\fIterminal type\fR] \fR(+)
3319Tests if \fIterminal type\fR (or the current value of \fBTERM\fR if no
3320\fIterminal type\fR is given) has an entry in the hosts termcap(5) or
3321terminfo(5) database. Prints the terminal type to stdout and returns 0
3322if an entry is present otherwise returns 1.
3323.TP 8
3324.B time \fR[\fIcommand\fR]
3325Executes \fIcommand\fR (which must be a simple command, not an alias,
3326a pipeline, a command list or a parenthesized command list)
3327and prints a time summary as described under the \fBtime\fR variable.
3328If necessary, an extra shell is created to print the time statistic when
3329the command completes.
3330Without \fIcommand\fR, prints a time summary for the current shell and its
3331children.
3332.TP 8
3333.B umask \fR[\fIvalue\fR]
3334Sets the file creation mask to \fIvalue\fR, which is given in octal.
3335Common values for the mask are
3336002, giving all access to the group and read and execute access to others, and
3337022, giving read and execute access to the group and others.
3338Without \fIvalue\fR, prints the current file creation mask.
3339.TP 8
3340.B unalias \fIpattern
3341.br
3342Removes all aliases whose names match \fIpattern\fR.
3343`unalias *' thus removes all aliases.
3344It is not an error for nothing to be \fIunalias\fRed.
3345.TP 8
3346.B uncomplete \fIpattern\fR (+)
3347Removes all completions whose names match \fIpattern\fR.
3348`uncomplete *' thus removes all completions.
3349It is not an error for nothing to be \fIuncomplete\fRd.
3350.TP 8
3351.B unhash
3352Disables use of the internal hash table to speed location of
3353executed programs.
3354.TP 8
3355.B universe \fIuniverse\fR (+)
3356Sets the universe to \fIuniverse\fR.  (Masscomp/RTU only)
3357.TP 8
3358.B unlimit \fR[\fB\-h\fR] [\fIresource\fR]
3359Removes the limitation on \fIresource\fR or, if no \fIresource\fR is
3360specified, all \fIresource\fR limitations.
3361With \fB\-h\fR, the corresponding hard limits are removed.
3362Only the super-user may do this.
3363Note that \fBunlimit\fR may not exit successful, since most systems
3364do not allow \fIdescriptors\fR to be unlimited.
3365.TP 8
3366.B unset \fIpattern
3367Removes all variables whose names match \fIpattern\fR, unless they are read-only.
3368`unset *' thus removes all variables unless they are read-only;
3369this is a bad idea.
3370It is not an error for nothing to be \fIunset\fR.
3371.TP 8
3372.B unsetenv \fIpattern
3373Removes all environment variables whose names match \fIpattern\fR.
3374`unsetenv *' thus removes all environment variables;
3375this is a bad idea.
3376It is not an error for nothing to be \fIunsetenv\fRed.
3377.TP 8
3378.B ver \fR[\fIsystype\fR [\fIcommand\fR]] (+)
3379Without arguments, prints \fBSYSTYPE\fR.  With \fIsystype\fR, sets \fBSYSTYPE\fR
3380to \fIsystype\fR.  With \fIsystype\fR and \fIcommand\fR, executes \fIcommand\fR
3381under \fIsystype\fR.  \fIsystype\fR may be `bsd4.3' or `sys5.3'.
3382(Domain/OS only)
3383.TP 8
3384.B wait
3385The shell waits for all background jobs.  If the shell is interactive, an
3386interrupt will disrupt the wait and cause the shell to print the names and job
3387numbers of all outstanding jobs.
3388.TP 8
3389.B warp \fIuniverse\fR (+)
3390Sets the universe to \fIuniverse\fR.  (Convex/OS only)
3391.TP 8
3392.B watchlog \fR(+)
3393An alternate name for the \fIlog\fR builtin command (q.v.).
3394Available only if the shell was so compiled;
3395see the \fBversion\fR shell variable.
3396.TP 8
3397.B where \fIcommand\fR (+)
3398Reports all known instances of \fIcommand\fR, including aliases, builtins and
3399executables in \fBpath\fR.
3400.TP 8
3401.B which\fR \fIcommand\fR (+)
3402Displays the command that will be executed by the shell after substitutions,
3403\fBpath\fR searching, etc.
3404The builtin command is just like \fIwhich\fR(1), but it correctly reports
3405\fItcsh\fR aliases and builtins and is 10 to 100 times faster.
3406See also the \fIwhich-command\fR editor command.
3407.PP
3408.B while (\fIexpr\fB)\fR
3409.br
3410\&...
3411.PD 0
3412.TP 8
3413.B end
3414Executes the commands between the \fIwhile\fR and the matching \fIend\fR
3415while \fIexpr\fR (an expression, as described under \fBExpressions\fR)
3416evaluates non-zero.
3417\fIwhile\fR and \fIend\fR must appear alone on their input lines.
3418\fIbreak\fR and \fIcontinue\fR may be used to terminate or continue the
3419loop prematurely.
3420If the input is a terminal, the user is prompted the first time
3421through the loop as with \fIforeach\fR.
3422.PD
3423.SS "Special aliases (+)"
3424If set, each of these aliases executes automatically at the indicated time.
3425They are all initially undefined.
3426.TP 8
3427.B beepcmd
3428Runs when the shell wants to ring the terminal bell.
3429.TP 8
3430.B cwdcmd
3431Runs after every change of working directory.  For example, if the user is
3432working on an X window system using \fIxterm\fR(1) and a re-parenting window
3433manager that supports title bars such as \fItwm\fR(1) and does
3434.RS +8
3435.IP "" 4
3436> alias cwdcmd  'echo \-n "^[]2;${HOST}:$cwd ^G"'
3437.PP
3438then the shell will change the title of the running \fIxterm\fR(1)
3439to be the name of the host, a colon, and the full current working directory.
3440A fancier way to do that is
3441.IP "" 4
3442> alias cwdcmd 'echo \-n "^[]2;${HOST}:$cwd^G^[]1;${HOST}^G"'
3443.PP
3444This will put the hostname and working directory on the title bar but
3445only the hostname in the icon manager menu.
3446.PP
3447Note that putting a \fIcd\fR, \fIpushd\fR or \fIpopd\fR in \fIcwdcmd\fR
3448may cause an infinite loop.  It is the author's opinion that anyone doing
3449so will get what they deserve.
3450.RE
3451.TP 8
3452.B jobcmd
3453Runs before each command gets executed, or when the command changes state.
3454This is similar to \fIpostcmd\fR, but it does not print builtins.
3455.RS +8
3456.IP "" 4
3457> alias jobcmd  'echo \-n "^[]2\e;\e!#^G"'
3458.PP
3459then executing \fIvi foo.c\fR will put the command string in the xterm title bar.
3460.RE
3461.TP 8
3462.B helpcommand
3463Invoked by the \fBrun-help\fR editor command.  The command name for which help
3464is sought is passed as sole argument.
3465For example, if one does
3466.RS +8
3467.IP "" 4
3468> alias helpcommand '\e!:1 --help'
3469.PP
3470then the help display of the command itself will be invoked, using the GNU
3471help calling convention.
3472Currently there is no easy way to account for various calling conventions (e.g.,
3473the customary Unix `-h'), except by using a table of many commands.
3474.RE
3475.TP 8
3476.B periodic
3477Runs every \fBtperiod\fR minutes.  This provides a convenient means for
3478checking on common but infrequent changes such as new mail.  For example,
3479if one does
3480.RS +8
3481.IP "" 4
3482> set tperiod = 30
3483.br
3484> alias periodic checknews
3485.PP
3486then the \fIchecknews\fR(1) program runs every 30 minutes.
3487If \fIperiodic\fR is set but \fBtperiod\fR is unset or set to 0,
3488\fIperiodic\fR behaves like \fIprecmd\fR.
3489.RE
3490.TP 8
3491.B precmd
3492Runs just before each prompt is printed.  For example, if one does
3493.RS +8
3494.IP "" 4
3495> alias precmd date
3496.PP
3497then \fIdate\fR(1) runs just before the shell prompts for each command.
3498There are no limits on what \fIprecmd\fR can be set to do, but discretion
3499should be used.
3500.RE
3501.TP 8
3502.B postcmd
3503Runs before each command gets executed.
3504.RS +8
3505.IP "" 4
3506> alias postcmd  'echo \-n "^[]2\e;\e!#^G"'
3507.PP
3508then executing \fIvi foo.c\fR will put the command string in the xterm title bar.
3509.RE
3510.TP 8
3511.B shell
3512Specifies the interpreter for executable scripts which do not themselves
3513specify an interpreter.  The first word should be a full path name to the
3514desired interpreter (e.g., `/bin/csh' or `/usr/local/bin/tcsh').
3515.SS "Special shell variables"
3516The variables described in this section have special meaning to the shell.
3517.PP
3518The shell sets \fBaddsuffix\fR, \fBargv\fR, \fBautologout\fR, \fBcsubstnonl\fR, \fBcommand\fR, \fBecho_style\fR,
3519\fBedit\fR, \fBgid\fR, \fBgroup\fR, \fBhome\fR, \fBloginsh\fR, \fBoid\fR, \fBpath\fR,
3520\fBprompt\fR, \fBprompt2\fR, \fBprompt3\fR, \fBshell\fR, \fBshlvl\fR,
3521\fBtcsh\fR, \fBterm\fR, \fBtty\fR, \fBuid\fR, \fBuser\fR and \fBversion\fR at
3522startup; they do not change thereafter unless changed by the user.  The shell
3523updates \fBcwd\fR, \fBdirstack\fR, \fBowd\fR and \fBstatus\fR when necessary,
3524and sets \fBlogout\fR on logout.
3525.PP
3526The shell synchronizes \fBafsuser\fR, \fBgroup\fR, \fBhome\fR, \fBpath\fR, \fBshlvl\fR,
3527\fBterm\fR and \fBuser\fR with the environment variables of the same names:
3528whenever the environment variable changes the shell changes the corresponding
3529shell variable to match (unless the shell variable is read-only) and vice
3530versa.  Note that although \fBcwd\fR and \fBPWD\fR have identical meanings, they
3531are not synchronized in this manner, and that the shell automatically
3532interconverts the different formats of \fBpath\fR and \fBPATH\fR.
3533.TP 8
3534.B addsuffix \fR(+)
3535If set, filename completion adds `/' to the end of directories and a space
3536to the end of normal files when they are matched exactly.
3537Set by default.
3538.TP 8
3539.B afsuser \fR(+)
3540If set, \fBautologout\fR's autolock feature uses its value instead of
3541the local username for kerberos authentication.
3542.TP 8
3543.B ampm \fR(+)
3544If set, all times are shown in 12-hour AM/PM format.
3545.TP 8
3546.B argv
3547The arguments to the shell.  Positional parameters are taken from \fBargv\fR,
3548i.e., `$1' is replaced by `$argv[1]', etc.
3549Set by default, but usually empty in interactive shells.
3550.TP 8
3551.B autocorrect \fR(+)
3552If set, the \fIspell-word\fR editor command is invoked automatically before
3553each completion attempt.
3554.TP 8
3555.B autoexpand \fR(+)
3556If set, the \fIexpand-history\fR editor command is invoked automatically
3557before each completion attempt.
3558.TP 8
3559.B autolist \fR(+)
3560If set, possibilities are listed after an ambiguous completion.
3561If set to `ambiguous', possibilities are listed only when no new
3562characters are added by completion.
3563.TP 8
3564.B autologout \fR(+)
3565The first word is the number of minutes of inactivity before automatic
3566logout.  The optional second word is the number of minutes of inactivity
3567before automatic locking.
3568When the shell automatically logs out,
3569it prints `auto-logout', sets the variable logout to `automatic' and exits.
3570When the shell automatically locks, the user is required to enter his password
3571to continue working.  Five incorrect attempts result in automatic logout.
3572Set to `60' (automatic logout after 60 minutes, and no locking) by default
3573in login and superuser shells, but not if the shell thinks it is running
3574under a window system (i.e., the \fBDISPLAY\fR environment variable is set),
3575the tty is a pseudo-tty (pty) or the shell was not so compiled (see the
3576\fBversion\fR shell variable).
3577See also the \fBafsuser\fR and \fBlogout\fR shell variables.
3578.TP 8
3579.B backslash_quote \fR(+)
3580If set, backslashes (`\\') always quote `\\', `'', and `"'.  This may make
3581complex quoting tasks easier, but it can cause syntax errors in \fIcsh\fR(1)
3582scripts.
3583.TP 8
3584.B catalog
3585The file name of the message catalog.
3586If set, tcsh use `tcsh.${catalog}' as a message catalog instead of
3587default `tcsh'.
3588.TP 8
3589.B cdpath
3590A list of directories in which \fIcd\fR should search for
3591subdirectories if they aren't found in the current directory.
3592.TP 8
3593.B color
3594If set, it enables color display for the builtin \fBls\-F\fR and it passes
3595\fB\-\-color=auto\fR to \fBls\fR.  Alternatively, it can be set to only
3596\fBls\-F\fR or only \fBls\fR to enable color to only one command.  Setting
3597it to nothing is equivalent to setting it to \fB(ls\-F ls)\fR.
3598.TP 8
3599.B colorcat
3600If set, it enables color escape sequence for NLS message files.
3601And display colorful NLS messages.
3602.TP 8
3603.B command \fR(+)
3604If set, the command which was passed to the shell with the \fB-c\fR flag (q.v.).
3605.TP 8
3606.B complete \fR(+)
3607If set to `enhance', completion 1) ignores case and 2) considers
3608periods, hyphens and underscores (`.', `\-' and `_') to be word
3609separators and hyphens and underscores to be equivalent. If set to
3610`igncase', the completion becomes case insensitive.
3611.TP 8
3612.B continue \fR(+)
3613If set to a list of commands, the shell will continue the listed
3614commands, instead of starting a new one.
3615.TP 8
3616.B continue_args \fR(+)
3617Same as continue, but the shell will execute:
3618.RS +8
3619.IP "" 4
3620echo `pwd` $argv > ~/.<cmd>_pause; %<cmd>
3621.RE
3622.TP 8
3623.B correct \fR(+)
3624If set to `cmd', commands are automatically spelling-corrected.
3625If set to `complete', commands are automatically completed.
3626If set to `all', the entire command line is corrected.
3627.TP 8
3628.B csubstnonl \fR(+)
3629If set, newlines and carriage returns in command substitution are
3630replaced by spaces.  Set by default.
3631.TP 8
3632.B cwd
3633The full pathname of the current directory.
3634See also the \fBdirstack\fR and \fBowd\fR shell variables.
3635.TP 8
3636.B dextract \fR(+)
3637If set, `pushd +\fIn\fR' extracts the \fIn\fRth directory from the directory
3638stack rather than rotating it to the top.
3639.TP 8
3640.B dirsfile \fR(+)
3641The default location in which `dirs \-S' and `dirs \-L' look for
3642a history file.  If unset, \fI~/.cshdirs\fR is used.
3643Because only \fI~/.tcshrc\fR is normally sourced before \fI~/.cshdirs\fR,
3644\fBdirsfile\fR should be set in \fI~/.tcshrc\fR rather than \fI~/.login\fR.
3645.TP 8
3646.B dirstack \fR(+)
3647An array of all the directories on the directory stack.
3648`$dirstack[1]' is the current working directory, `$dirstack[2]'
3649the first directory on the stack, etc.
3650Note that the current working directory is `$dirstack[1]' but `=0' in
3651directory stack substitutions, etc.
3652One can change the stack arbitrarily by setting \fBdirstack\fR,
3653but the first element (the current working directory) is always correct.
3654See also the \fBcwd\fR and \fBowd\fR shell variables.
3655.TP 8
3656.B dspmbyte \fR(+)
3657Has an affect iff 'dspm' is listed as part of the \fBversion\fR shell variable.
3658If set to `euc', it enables display and editing EUC-kanji(Japanese) code.
3659If set to `sjis', it enables display and editing Shift-JIS(Japanese) code.
3660If set to `big5', it enables display and editing Big5(Chinese) code.
3661If set to `utf8', it enables display and editing Utf8(Unicode) code.
3662If set to the following format, it enables display and editing of original
3663multi-byte code format:
3664.RS +8
3665.IP "" 4
3666> set dspmbyte = 0000....(256 bytes)....0000
3667.PP
3668The table requires \fBjust\fR 256 bytes.  Each character of 256 characters
3669corresponds (from left to right) to the ASCII codes 0x00, 0x01, ... 0xff.  Each
3670character
3671.\" (position in this table?)
3672is set to number 0,1,2 and 3.  Each number has the following meaning:
3673.br
3674  0 ... not used for multi-byte characters.
3675.br
3676  1 ... used for the first byte of a multi-byte character.
3677.br
3678  2 ... used for the second byte of a multi-byte character.
3679.br
3680  3 ... used for both the first byte and second byte of a multi-byte character.
3681.\" SHK: I tried my best to get the following to be grammatically correct.
3682.\" However, I still don't understand what's going on here.  In the
3683 \" following example, there are three bytes, but the text seems to refer to
3684 \" each nybble as a character.  What's going on here?  It this 3-byte code
3685 \" in the table?  The text above seems to imply that there are 256
3686 \" characters/bytes in the table.  If I get some more info on this (perhaps
3687 \" a complete example), I could fix the text to be grammatically correct.
3688 \" (steve.kelem@xilinx.com 1999/09/13)
3689.PP
3690  Example:
3691.br
3692If set to `001322', the first character (means 0x00 of the ASCII code) and
3693second character (means 0x01 of ASCII code) are set to `0'.  Then, it is not
3694used for multi-byte characters.  The 3rd character (0x02) is set to '1',
3695indicating that it is used for the first byte of a multi-byte character.
3696The 4th character(0x03) is set '3'.  It is used for both the first byte and
3697the second byte of a multi-byte character.  The 5th and 6th characters
3698(0x04,0x05) are set to '2', indicating that they are used for the second
3699byte of a multi-byte character.
3700.PP
3701The GNU fileutils version of ls cannot display multi-byte
3702filenames without the -N ( --literal ) option.   If you are using
3703this version, set the second word of dspmbyte to "ls".  If not, for
3704example, "ls-F -l" cannot display multi-byte filenames.
3705.PP
3706  Note:
3707.br
3708This variable can only be used if KANJI and DSPMBYTE has been defined at
3709compile time.
3710.RE
3711.TP 8
3712.B dunique \fR(+)
3713If set, \fIpushd\fR removes any instances of \fIname\fR
3714from the stack before pushing it onto the stack.
3715.TP 8
3716.B echo
3717If set, each command with its arguments is echoed just before it is
3718executed.  For non-builtin commands all expansions occur before
3719echoing.  Builtin commands are echoed before command and filename
3720substitution, because these substitutions are then done selectively.
3721Set by the \fB\-x\fR command line option.
3722.TP 8
3723.B echo_style \fR(+)
3724The style of the \fIecho\fR builtin.  May be set to
3725.PP
3726.RS +8
3727.PD 0
3728.TP 8
3729bsd
3730Don't echo a newline if the first argument is `\-n'.
3731.TP 8
3732sysv
3733Recognize backslashed escape sequences in echo strings.
3734.TP 8
3735both
3736Recognize both the `\-n' flag and backslashed escape sequences; the default.
3737.TP 8
3738none
3739Recognize neither.
3740.PD
3741.PP
3742Set by default to the local system default.  The BSD and System V
3743options are described in the \fIecho\fR(1) man pages on the appropriate
3744systems.
3745.RE
3746.TP 8
3747.B edit \fR(+)
3748If set, the command-line editor is used.  Set by default in interactive
3749shells.
3750.TP 8
3751.B ellipsis \fR(+)
3752If set, the `%c'/`%.' and `%C' prompt sequences (see the \fBprompt\fR
3753shell variable) indicate skipped directories with an ellipsis (`...')
3754instead of `/<skipped>'.
3755.TP 8
3756.B fignore \fR(+)
3757Lists file name suffixes to be ignored by completion.
3758.TP 8
3759.B filec
3760In \fItcsh\fR, completion is always used and this variable is ignored
3761by default. If
3762.B edit
3763is unset, then the traditional \fIcsh\fR completion is used.
3764If set in \fIcsh\fR, filename completion is used.
3765.TP 8
3766.B gid \fR(+)
3767The user's real group ID.
3768.TP 8
3769.B group \fR(+)
3770The user's group name.
3771.TP 8
3772.B histchars
3773A string value determining the characters used in \fBHistory
3774substitution\fR (q.v.).  The first character of its value is used as
3775the history substitution character, replacing the default character
3776`!'.  The second character of its value replaces the character `^' in
3777quick substitutions.
3778.TP 8
3779.B histdup \fR(+)
3780Controls handling of duplicate entries in the history list.  If set to
3781`all' only unique history events are entered in the history list.  If
3782set to `prev' and the last history event is the same as the current
3783command, then the current command is not entered in the history.  If
3784set to `erase' and the same event is found in the history list, that
3785old event gets erased and the current one gets inserted.  Note that the
3786`prev' and `all' options renumber history events so there are no gaps.
3787.TP 8
3788.B histfile \fR(+)
3789The default location in which `history \-S' and `history \-L' look for
3790a history file.  If unset, \fI~/.history\fR is used.  \fBhistfile\fR is
3791useful when sharing the same home directory between different machines,
3792or when saving separate histories on different terminals.  Because only
3793\fI~/.tcshrc\fR is normally sourced before \fI~/.history\fR,
3794\fBhistfile\fR should be set in \fI~/.tcshrc\fR rather than
3795\fI~/.login\fR.
3796.TP 8
3797.B histlit \fR(+)
3798If set, builtin and editor commands and the \fBsavehist\fR mechanism
3799use the literal (unexpanded) form of lines in the history list.  See
3800also the \fItoggle-literal-history\fR editor command.
3801.TP 8
3802.B history
3803The first word indicates the number of history events to save.  The
3804optional second word (+) indicates the format in which history is
3805printed; if not given, `%h\\t%T\\t%R\\n' is used.  The format sequences
3806are described below under \fBprompt\fR; note the variable meaning of
3807`%R'.  Set to `100' by default.
3808.TP 8
3809.B home
3810Initialized to the home directory of the invoker.  The filename
3811expansion of `\fI~\fR' refers to this variable.
3812.TP 8
3813.B ignoreeof
3814If set to the empty string or `0' and the input device is a terminal,
3815the \fIend-of-file\fR command (usually generated by the user by typing
3816`^D' on an empty line) causes the shell to print `Use "exit" to leave
3817tcsh.' instead of exiting.  This prevents the shell from accidentally
3818being killed.  Historically this setting exited after 26 successive
3819EOF's to avoid infinite loops.  If set to a number \fIn\fR, the shell
3820ignores \fIn - 1\fR consecutive \fIend-of-file\fRs and exits on the
3821\fIn\fRth.  (+) If unset, `1' is used, i.e., the shell exits on a
3822single `^D'.
3823.TP 8
3824.B implicitcd \fR(+)
3825If set, the shell treats a directory name typed as a command as though
3826it were a request to change to that directory.  If set to \fIverbose\fR,
3827the change of directory is echoed to the standard output.  This behavior
3828is inhibited in non-interactive shell scripts, or for command strings
3829with more than one word.  Changing directory takes precedence over
3830executing a like-named command, but it is done after alias
3831substitutions.  Tilde and variable expansions work as expected.
3832.TP 8
3833.B inputmode \fR(+)
3834If set to `insert' or `overwrite', puts the editor into that input mode
3835at the beginning of each line.
3836.TP 8
3837.B killdup \fR(+)
3838Controls handling of duplicate entries in the kill ring.  If set to
3839`all' only unique strings are entered in the kill ring.  If set to
3840`prev' and the last killed string is the same as the current killed
3841string, then the current string is not entered in the ring.  If set
3842to `erase' and the same string is found in the kill ring, the old
3843string is erased and the current one is inserted.
3844.TP 8
3845.B killring \fR(+)
3846Indicates the number of killed strings to keep in memory.  Set to `30'
3847by default.  If unset or set to less than `2', the shell will only
3848keep the most recently killed string.
3849Strings are put in the killring by the editor commands that delete
3850(kill) strings of text, e.g. \fIbackward-delete-word\fR,
3851\fIkill-line\fR, etc, as well as the \fIcopy-region-as-kill\fR command.
3852The \fIyank\fR editor command will yank the most recently killed string
3853into the command-line, while \fIyank-pop\fR (see \fBEditor commands\fR)
3854can be used to yank earlier killed strings.
3855.TP 8
3856.B listflags \fR(+)
3857If set to `x', `a' or `A', or any combination thereof (e.g., `xA'), they
3858are used as flags to \fIls\-F\fR, making it act like `ls \-xF', `ls
3859\-Fa', `ls \-FA' or a combination (e.g., `ls \-FxA'): `a' shows all
3860files (even if they start with a `.'), `A' shows all files but `.' and
3861`..', and `x' sorts across instead of down.  If the second word of
3862\fBlistflags\fR is set, it is used as the path to `ls(1)'.
3863.TP 8
3864.B listjobs \fR(+)
3865If set, all jobs are listed when a job is suspended.  If set to `long',
3866the listing is in long format.
3867.TP 8
3868.B listlinks \fR(+)
3869If set, the \fIls\-F\fR builtin command shows the type of file to which
3870each symbolic link points.
3871.TP 8
3872.B listmax \fR(+)
3873The maximum number of items which the \fIlist-choices\fR editor command
3874will list without asking first.
3875.TP 8
3876.B listmaxrows \fR(+)
3877The maximum number of rows of items which the \fIlist-choices\fR editor
3878command will list without asking first.
3879.TP 8
3880.B loginsh \fR(+)
3881Set by the shell if it is a login shell.  Setting or unsetting it
3882within a shell has no effect.  See also \fBshlvl\fR.
3883.TP 8
3884.B logout \fR(+)
3885Set by the shell to `normal' before a normal logout, `automatic' before
3886an automatic logout, and `hangup' if the shell was killed by a hangup
3887signal (see \fBSignal handling\fR).  See also the \fBautologout\fR
3888shell variable.
3889.TP 8
3890.B mail
3891The names of the files or directories to check for incoming mail,
3892separated by whitespace, and optionally preceded by a numeric word.
3893Before each prompt, if 10 minutes have passed since the last check, the
3894shell checks each file and says `You have new mail.' (or, if \fBmail\fR
3895contains multiple files, `You have new mail in \fIname\fR.') if the
3896filesize is greater than zero in size and has a modification time
3897greater than its access time.
3898.PP
3899.RS +8
3900.PD
3901.PP
3902If you are in a login shell, then no mail file is reported unless it has
3903been modified after the time the shell has started up, to prevent
3904redundant notifications.  Most login programs will tell you whether or not
3905you have mail when you log in.
3906.PP
3907If a file specified in \fBmail\fR is a directory, the shell will count each
3908file within that directory as a separate message, and will report `You have
3909\fIn\fR mails.' or `You have \fIn\fR mails in \fIname\fR.' as appropriate.
3910This functionality is provided primarily for those systems which store mail
3911in this manner, such as the Andrew Mail System.
3912.PP
3913If the first word of \fBmail\fR is numeric it is taken as a different mail
3914checking interval, in seconds.
3915.PP
3916Under very rare circumstances, the shell may report `You have mail.' instead
3917of `You have new mail.'
3918.RE
3919.TP 8
3920.B matchbeep \fR(+)
3921If set to `never', completion never beeps.
3922If set to `nomatch', it beeps only when there is no match.
3923If set to `ambiguous', it beeps when there are multiple matches.
3924If set to `notunique', it beeps when there is one exact and other longer matches.
3925If unset, `ambiguous' is used.
3926.TP 8
3927.B nobeep \fR(+)
3928If set, beeping is completely disabled.
3929See also \fBvisiblebell\fR.
3930.TP 8
3931.B noclobber
3932If set, restrictions are placed on output redirection to insure that files
3933are not accidentally destroyed and that `>>' redirections refer to existing
3934files, as described in the \fBInput/output\fR section.
3935.TP 8
3936.B noding
3937If set, disable the printing of `DING!' in the \fBprompt\fR time
3938specifiers at the change of hour.
3939.TP 8
3940.B noglob
3941If set, \fBFilename substitution\fR and \fBDirectory stack substitution\fR
3942(q.v.) are inhibited.  This is most useful in shell scripts which do not deal
3943with filenames, or after a list of filenames has been obtained and further
3944expansions are not desirable.
3945.TP 8
3946.B nokanji \fR(+)
3947If set and the shell supports Kanji (see the \fBversion\fR shell variable),
3948it is disabled so that the meta key can be used.
3949.TP 8
3950.B nonomatch
3951If set, a \fBFilename substitution\fR or \fBDirectory stack substitution\fR
3952(q.v.) which does not match any
3953existing files is left untouched rather than causing an error.
3954It is still an error for the substitution to be
3955malformed, e.g., `echo [' still gives an error.
3956.TP 8
3957.B nostat \fR(+)
3958A list of directories (or glob-patterns which match directories; see
3959\fBFilename substitution\fR) that should not be \fIstat\fR(2)ed during a
3960completion operation.  This is usually used to exclude directories which
3961take too much time to \fIstat\fR(2), for example \fI/afs\fR.
3962.TP 8
3963.B notify
3964If set, the shell announces job completions asynchronously.
3965The default is to present job completions just before printing a prompt.
3966.TP 8
3967.B oid \fR(+)
3968The user's real organization ID.  (Domain/OS only)
3969.TP 8
3970.B owd \fR(+)
3971The old working directory, equivalent to the `\-' used by \fIcd\fR and \fIpushd\fR.
3972See also the \fBcwd\fR and \fBdirstack\fR shell variables.
3973.TP 8
3974.B path
3975A list of directories in which to look for executable commands.
3976A null word specifies the current directory.
3977If there is no \fBpath\fR variable then only full path names will execute.
3978\fBpath\fR is set by the shell at startup from the \fBPATH\fR environment
3979variable or, if \fBPATH\fR does not exist, to a system-dependent default
3980something like `(/usr/local/bin /usr/bsd /bin /usr/bin .)'.
3981The shell may put `.' first or last in \fBpath\fR or omit it entirely
3982depending on how it was compiled; see the \fBversion\fR shell variable.
3983A shell which is given neither the \fB\-c\fR nor the \fB\-t\fR option
3984hashes the contents of the directories in \fBpath\fR after
3985reading \fI~/.tcshrc\fR and each time \fBpath\fR is reset.
3986If one adds a new command to a directory in \fBpath\fR while the shell
3987is active, one may need to do a \fIrehash\fR for the shell to find it.
3988.TP 8
3989.B printexitvalue \fR(+)
3990If set and an interactive program exits with a non-zero status, the shell
3991prints `Exit \fBstatus\fR'.
3992.TP 8
3993.B prompt
3994The string which is printed before reading each command from the terminal.
3995\fBprompt\fR may include any of the following formatting sequences (+), which
3996are replaced by the given information:
3997.PP
3998.RS +8
3999.PD 0
4000.TP 4
4001%/
4002The current working directory.
4003.TP 4
4004%~ or %d
4005The current working directory, but with one's home directory
4006represented by `~' and other users' home directories represented by
4007`~user' as per \fBFilename substitution\fR.  `~user' substitution
4008happens only if the shell has already used `~\fIuser\fR' in a pathname
4009in the current session.
4010.TP 4
4011%c[[0]\fIn\fR], %.[[0]\fIn\fR]
4012The trailing component of the current working directory, or \fIn\fR
4013trailing components if a digit \fIn\fR is given.
4014If \fIn\fR begins with `0', the number of skipped components precede
4015the trailing component(s) in the format `/<\fIskipped\fR>trailing'.
4016If the \fBellipsis\fR shell variable is set, skipped components
4017are represented by an ellipsis so the whole becomes `...trailing'.
4018`~' substitution is done as in `%~' above, but the `~' component
4019is ignored when counting trailing components.
4020.TP 4
4021%C
4022Like %c, but without `~' substitution.
4023.TP 4
4024%h, %!, !
4025The current history event number.
4026.TP 4
4027%M
4028The full hostname.
4029.TP 4
4030%m
4031The hostname up to the first `.'.
4032.TP 4
4033%S (%s)
4034Start (stop) standout mode.
4035.TP 4
4036%B (%b)
4037Start (stop) boldfacing mode.
4038.TP 4
4039%U (%u)
4040Start (stop) underline mode.
4041.TP 4
4042%t, %@
4043The time of day in 12-hour AM/PM format.
4044.TP 4
4045%T
4046Like `%t', but in 24-hour format (but see the \fBampm\fR shell variable).
4047.TP 4
4048%p
4049The `precise' time of day in 12-hour AM/PM format, with seconds.
4050.TP 4
4051%P
4052Like `%p', but in 24-hour format (but see the \fBampm\fR shell variable).
4053.TP 4
4054\e\fIc\fR
4055\fIc\fR is parsed as in \fIbindkey\fR.
4056.TP 4
4057^\fIc\fR
4058\fIc\fR is parsed as in \fIbindkey\fR.
4059.TP 4
4060%%
4061A single `%'.
4062.TP 4
4063%n
4064The user name.
4065.TP 4
4066%j
4067The number of jobs.
4068.TP 4
4069%k
4070The weekday in `Day' format.
4071.TP 4
4072%D
4073The day in `dd' format.
4074.TP 4
4075%w
4076The month in `Mon' format.
4077.TP 4
4078%W
4079The month in `mm' format.
4080.TP 4
4081%y
4082The year in `yy' format.
4083.TP 4
4084%Y
4085The year in `yyyy' format.
4086.TP 4
4087%l
4088The shell's tty.
4089.TP 4
4090%L
4091Clears from the end of the prompt to end of the display or the end of the line.
4092.TP 4
4093%$
4094Expands the shell or environment variable name immediately after the `$'.
4095.TP 4
4096%#
4097`>' (or the first character of the \fBpromptchars\fR shell variable)
4098for normal users, `#' (or the second character of \fBpromptchars\fR)
4099for the superuser.
4100.TP 4
4101%{\fIstring\fR%}
4102Includes \fIstring\fR as a literal escape sequence.
4103It should be used only to change terminal attributes and
4104should not move the cursor location.  This
4105cannot be the last sequence in \fBprompt\fR.
4106.TP 4
4107%?
4108The return code of the command executed just before the prompt.
4109.TP 4
4110%R
4111In \fBprompt2\fR, the status of the parser.
4112In \fBprompt3\fR, the corrected string.
4113In \fBhistory\fR, the history string.
4114.PD
4115.PP
4116`%B', `%S', `%U' and `%{\fIstring\fR%}' are available in only
4117eight-bit-clean shells; see the \fBversion\fR shell variable.
4118.PP
4119The bold, standout and underline sequences are often used to distinguish a
4120superuser shell.  For example,
4121.IP "" 4
4122> set prompt = "%m [%h] %B[%@]%b [%/] you rang? "
4123.br
4124tut [37] \fB[2:54pm]\fR [/usr/accts/sys] you rang? _
4125.PP
4126If `%t', `%@', `%T', `%p', or `%P' is used, and \fBnoding\fR is not set,
4127then print `DING!' on the change of hour (i.e, `:00' minutes) instead of
4128the actual time.
4129.PP
4130Set by default to `%# ' in interactive shells.
4131.RE
4132.TP 8
4133.B prompt2 \fR(+)
4134The string with which to prompt in \fIwhile\fR and \fIforeach\fR loops and
4135after lines ending in `\\'.
4136The same format sequences may be used as in \fBprompt\fR (q.v.);
4137note the variable meaning of `%R'.
4138Set by default to `%R? ' in interactive shells.
4139.TP 8
4140.B prompt3 \fR(+)
4141The string with which to prompt when confirming automatic spelling correction.
4142The same format sequences may be used as in \fBprompt\fR (q.v.);
4143note the variable meaning of `%R'.
4144Set by default to `CORRECT>%R (y|n|e|a)? ' in interactive shells.
4145.TP 8
4146.B promptchars \fR(+)
4147If set (to a two-character string), the `%#' formatting sequence in the
4148\fBprompt\fR shell variable is replaced with the first character for
4149normal users and the second character for the superuser.
4150.TP 8
4151.B pushdtohome \fR(+)
4152If set, \fIpushd\fR without arguments does `pushd ~', like \fIcd\fR.
4153.TP 8
4154.B pushdsilent \fR(+)
4155If set, \fIpushd\fR and \fIpopd\fR do not print the directory stack.
4156.TP 8
4157.B recexact \fR(+)
4158If set, completion completes on an exact match even if a longer match is
4159possible.
4160.TP 8
4161.B recognize_only_executables \fR(+)
4162If set, command listing displays only files in the path that are
4163executable.  Slow.
4164.TP 8
4165.B rmstar \fR(+)
4166If set, the user is prompted before `rm *' is executed.
4167.TP 8
4168.B rprompt \fR(+)
4169The string to print on the right-hand side of the screen (after
4170the command input) when the prompt is being displayed on the left.
4171It recognizes the same formatting characters as \fBprompt\fR.
4172It will automatically disappear and reappear as necessary, to ensure that
4173command input isn't obscured, and will appear only if the prompt,
4174command input, and itself will fit together on the first line.
4175If \fBedit\fR isn't set, then \fBrprompt\fR will be printed after
4176the prompt and before the command input.
4177.TP 8
4178.B savedirs \fR(+)
4179If set, the shell does `dirs \-S' before exiting.
4180If the first word is set to a number, at most that many directory stack
4181entries are saved.
4182.TP 8
4183.B savehist
4184If set, the shell does `history \-S' before exiting.
4185If the first word is set to a number, at most that many lines are saved.
4186(The number must be less than or equal to \fBhistory\fR.)
4187If the second word is set to `merge', the history list is merged with
4188the existing history file instead of replacing it (if there is one) and
4189sorted by time stamp and the most recent events are retained.  (+)
4190.TP 8
4191.B sched \fR(+)
4192The format in which the \fIsched\fR builtin command prints scheduled events;
4193if not given, `%h\\t%T\\t%R\\n' is used.
4194The format sequences are described above under \fBprompt\fR;
4195note the variable meaning of `%R'.
4196.TP 8
4197.B shell
4198The file in which the shell resides.  This is used in forking
4199shells to interpret files which have execute bits set, but
4200which are not executable by the system.  (See the description
4201of \fBBuiltin and non-builtin command execution\fR.)  Initialized to the
4202(system-dependent) home of the shell.
4203.TP 8
4204.B shlvl \fR(+)
4205The number of nested shells.
4206Reset to 1 in login shells.
4207See also \fBloginsh\fR.
4208.TP 8
4209.B status
4210The status returned by the last command.  If it terminated
4211abnormally, then 0200 is added to the status.  Builtin commands
4212which fail return exit status `1', all other builtin commands
4213return status `0'.
4214.TP 8
4215.B symlinks \fR(+)
4216Can be set to several different values to control symbolic link (`symlink')
4217resolution:
4218.RS +8
4219.PP
4220If set to `chase', whenever the current directory changes to a directory
4221containing a symbolic link, it is expanded to the real name of the directory
4222to which the link points.  This does not work for the user's home directory;
4223this is a bug.
4224.PP
4225If set to `ignore', the shell tries to construct a current directory
4226relative to the current directory before the link was crossed.
4227This means that \fIcd\fRing through a symbolic link and then `cd ..'ing
4228returns one to the original directory.  This affects only builtin commands
4229and filename completion.
4230.PP
4231If set to `expand', the shell tries to fix symbolic links by actually expanding
4232arguments which look like path names.  This affects any command, not just
4233builtins.  Unfortunately, this does not work for hard-to-recognize filenames,
4234such as those embedded in command options.  Expansion may be prevented by
4235quoting.  While this setting is usually the most convenient, it is sometimes
4236misleading and sometimes confusing when it fails to recognize an argument
4237which should be expanded.  A compromise is to use `ignore' and use the
4238editor command \fInormalize-path\fR (bound by default to ^X-n) when necessary.
4239.PP
4240Some examples are in order.  First, let's set up some play directories:
4241.IP "" 4
4242> cd /tmp
4243.br
4244> mkdir from from/src to
4245.br
4246> ln \-s from/src to/dst
4247.PP
4248Here's the behavior with \fBsymlinks\fR unset,
4249.IP "" 4
4250> cd /tmp/to/dst; echo $cwd
4251.br
4252/tmp/to/dst
4253.br
4254> cd ..; echo $cwd
4255.br
4256/tmp/from
4257.PP
4258here's the behavior with \fBsymlinks\fR set to `chase',
4259.IP "" 4
4260> cd /tmp/to/dst; echo $cwd
4261.br
4262/tmp/from/src
4263.br
4264> cd ..; echo $cwd
4265.br
4266/tmp/from
4267.PP
4268here's the behavior with \fBsymlinks\fR set to `ignore',
4269.IP "" 4
4270> cd /tmp/to/dst; echo $cwd
4271.br
4272/tmp/to/dst
4273.br
4274> cd ..; echo $cwd
4275.br
4276/tmp/to
4277.PP
4278and here's the behavior with \fBsymlinks\fR set to `expand'.
4279.IP "" 4
4280> cd /tmp/to/dst; echo $cwd
4281.br
4282/tmp/to/dst
4283.br
4284> cd ..; echo $cwd
4285.br
4286/tmp/to
4287.br
4288> cd /tmp/to/dst; echo $cwd
4289.br
4290/tmp/to/dst
4291.br
4292> cd ".."; echo $cwd
4293.br
4294/tmp/from
4295.br
4296> /bin/echo ..
4297.br
4298/tmp/to
4299.br
4300> /bin/echo ".."
4301.br
4302\&..
4303.PP
4304Note that `expand' expansion 1) works just like `ignore' for builtins
4305like \fIcd\fR, 2) is prevented by quoting, and 3) happens before
4306filenames are passed to non-builtin commands.
4307.RE
4308.TP 8
4309.B tcsh \fR(+)
4310The version number of the shell in the format `R.VV.PP',
4311where `R' is the major release number, `VV' the current version
4312and `PP' the patchlevel.
4313.TP 8
4314.B term
4315The terminal type.  Usually set in \fI~/.login\fR as described under
4316\fBStartup and shutdown\fR.
4317.TP 8
4318.B time
4319If set to a number, then the \fItime\fR builtin (q.v.) executes automatically
4320after each command which takes more than that many CPU seconds.
4321If there is a second word, it is used as a format string for the output
4322of the \fItime\fR builtin.  (u) The following sequences may be used in the
4323format string:
4324.PP
4325.RS +8
4326.PD 0
4327.TP 4
4328%U
4329The time the process spent in user mode in cpu seconds.
4330.TP 4
4331%S
4332The time the process spent in kernel mode in cpu seconds.
4333.TP 4
4334%E
4335The elapsed (wall clock) time in seconds.
4336.TP 4
4337%P
4338The CPU percentage computed as (%U + %S) / %E.
4339.TP 4
4340%W
4341Number of times the process was swapped.
4342.TP 4
4343%X
4344The average amount in (shared) text space used in Kbytes.
4345.TP 4
4346%D
4347The average amount in (unshared) data/stack space used in Kbytes.
4348.TP 4
4349%K
4350The total space used (%X + %D) in Kbytes.
4351.TP 4
4352%M
4353The maximum memory the process had in use at any time in Kbytes.
4354.TP 4
4355%F
4356The number of major page faults (page needed to be brought from disk).
4357.TP 4
4358%R
4359The number of minor page faults.
4360.TP 4
4361%I
4362The number of input operations.
4363.TP 4
4364%O
4365The number of output operations.
4366.TP 4
4367%r
4368The number of socket messages received.
4369.TP 4
4370%s
4371The number of socket messages sent.
4372.TP 4
4373%k
4374The number of signals received.
4375.TP 4
4376%w
4377The number of voluntary context switches (waits).
4378.TP 4
4379%c
4380The number of involuntary context switches.
4381.PD
4382.PP
4383Only the first four sequences are supported on systems without BSD resource
4384limit functions.
4385The default time format is `%Uu %Ss %E %P %X+%Dk %I+%Oio %Fpf+%Ww' for
4386systems that support resource usage reporting and `%Uu %Ss %E %P' for
4387systems that do not.
4388.PP
4389Under Sequent's DYNIX/ptx, %X, %D, %K, %r and %s are not
4390available, but the following additional sequences are:
4391.PP
4392.PD 0
4393.TP 4
4394%Y
4395The number of system calls performed.
4396.TP 4
4397%Z
4398The number of pages which are zero-filled on demand.
4399.TP 4
4400%i
4401The number of times a process's resident set size was increased by the kernel.
4402.TP 4
4403%d
4404The number of times a process's resident set size was decreased by the kernel.
4405.TP 4
4406%l
4407The number of read system calls performed.
4408.TP 4
4409%m
4410The number of write system calls performed.
4411.TP 4
4412%p
4413The number of reads from raw disk devices.
4414.TP 4
4415%q
4416The number of writes to raw disk devices.
4417.PD
4418.PP
4419and the default time format is `%Uu %Ss %E %P %I+%Oio %Fpf+%Ww'.
4420Note that the CPU percentage can be higher than 100% on multi-processors.
4421.RE
4422.TP 8
4423.B tperiod \fR(+)
4424The period, in minutes, between executions of the \fIperiodic\fR special alias.
4425.TP 8
4426.B tty \fR(+)
4427The name of the tty, or empty if not attached to one.
4428.TP 8
4429.B uid \fR(+)
4430The user's real user ID.
4431.TP 8
4432.B user
4433The user's login name.
4434.TP 8
4435.B verbose
4436If set, causes the words of each
4437command to be printed, after history substitution (if any).
4438Set by the \fB\-v\fR command line option.
4439.TP 8
4440.B version \fR(+)
4441The version ID stamp.  It contains the shell's version number (see \fBtcsh\fR),
4442origin, release date, vendor, operating system and machine (see \fBVENDOR\fR,
4443\fBOSTYPE\fR and \fBMACHTYPE\fR) and a comma-separated
4444list of options which were set at compile time.
4445Options which are set by default in the distribution are noted.
4446.PP
4447.RS +8
4448.PD 0
4449.TP 6
44508b
4451The shell is eight bit clean; default
4452.TP 6
44537b
4454The shell is not eight bit clean
4455.TP 6
4456wide
4457The shell is multibyte encoding clean (like UTF-8)
4458.TP 6
4459nls
4460The system's NLS is used; default for systems with NLS
4461.TP 6
4462lf
4463Login shells execute \fI/etc/csh.login\fR before instead of after
4464\fI/etc/csh.cshrc\fR and \fI~/.login\fR before instead of after
4465\fI~/.tcshrc\fR and \fI~/.history\fR.
4466.TP 6
4467dl
4468`.' is put last in \fBpath\fR for security; default
4469.TP 6
4470nd
4471`.' is omitted from \fBpath\fR for security
4472.TP 6
4473vi
4474\fIvi\fR-style editing is the default rather than \fIemacs\fR
4475.TP 6
4476dtr
4477Login shells drop DTR when exiting
4478.TP 6
4479bye
4480\fIbye\fR is a synonym for \fIlogout\fR and \fIlog\fR
4481is an alternate name for \fIwatchlog\fR
4482.TP 6
4483al
4484\fBautologout\fR is enabled; default
4485.TP 6
4486kan
4487Kanji is used if appropriate according to locale settings,
4488unless the \fBnokanji\fR shell variable is set
4489.TP 6
4490sm
4491The system's \fImalloc\fR(3) is used
4492.TP 6
4493hb
4494The `#!<program> <args>' convention is emulated when executing shell scripts
4495.TP 6
4496ng
4497The \fInewgrp\fR builtin is available
4498.TP 6
4499rh
4500The shell attempts to set the \fBREMOTEHOST\fR environment variable
4501.TP 6
4502afs
4503The shell verifies your password with the kerberos server if local
4504authentication fails.  The \fBafsuser\fR shell variable or the
4505\fBAFSUSER\fR environment variable override your local username if set.
4506.PD
4507.PP
4508An administrator may enter additional strings to indicate differences
4509in the local version.
4510.RE
4511.TP 8
4512.B visiblebell \fR(+)
4513If set, a screen flash is used rather than the audible bell.
4514See also \fBnobeep\fR.
4515.TP 8
4516.B watch \fR(+)
4517A list of user/terminal pairs to watch for logins and logouts.
4518If either the user is `any' all terminals are watched for the given user
4519and vice versa.
4520Setting \fBwatch\fR to `(any any)' watches all users and terminals.
4521For example,
4522.RS +8
4523.IP "" 4
4524set watch = (george ttyd1 any console $user any)
4525.PP
4526reports activity of the user `george' on ttyd1, any user on the console, and
4527oneself (or a trespasser) on any terminal.
4528.PP
4529Logins and logouts are checked every 10 minutes by default, but the first
4530word of \fBwatch\fR can be set to a number to check every so many minutes.
4531For example,
4532.IP "" 4
4533set watch = (1 any any)
4534.PP
4535reports any login/logout once every minute.  For the impatient, the \fIlog\fR
4536builtin command triggers a \fBwatch\fR report at any time.  All current logins
4537are reported (as with the \fIlog\fR builtin) when \fBwatch\fR is first set.
4538.PP
4539The \fBwho\fR shell variable controls the format of \fBwatch\fR reports.
4540.RE
4541.TP 8
4542.B who \fR(+)
4543The format string for \fBwatch\fR messages.  The following sequences
4544are replaced by the given information:
4545.PP
4546.RS +8
4547.PD 0
4548.TP 4
4549%n
4550The name of the user who logged in/out.
4551.TP 4
4552%a
4553The observed action, i.e., `logged on', `logged off' or `replaced \fIolduser\fR on'.
4554.TP 4
4555%l
4556The terminal (tty) on which the user logged in/out.
4557.TP 4
4558%M
4559The full hostname of the remote host, or `local' if the login/logout was
4560from the local host.
4561.TP 4
4562%m
4563The hostname of the remote host up to the first `.'.
4564The full name is printed if it is an IP address or an X Window System display.
4565.PD
4566.PP
4567%M and %m are available on only systems that store the remote hostname in
4568\fI/etc/utmp\fR.
4569If unset, `%n has %a %l from %m.' is used, or `%n has %a %l.' on systems
4570which don't store the remote hostname.
4571.RE
4572.TP 8
4573.B wordchars \fR(+)
4574A list of non-alphanumeric characters to be considered part of a word by the
4575\fIforward-word\fR, \fIbackward-word\fR etc., editor commands.
4576If unset, `*?_\-.[]~=' is used.
4577.SH ENVIRONMENT
4578.TP 8
4579.B AFSUSER \fR(+)
4580Equivalent to the \fBafsuser\fR shell variable.
4581.TP 8
4582.B COLUMNS
4583The number of columns in the terminal.  See \fBTerminal management\fR.
4584.TP 8
4585.B DISPLAY
4586Used by X Window System (see \fIX\fR(1)).
4587If set, the shell does not set \fBautologout\fR (q.v.).
4588.TP 8
4589.B EDITOR
4590The pathname to a default editor.
4591See also the \fBVISUAL\fR environment variable
4592and the \fIrun-fg-editor\fR editor command.
4593.TP 8
4594.B GROUP \fR(+)
4595Equivalent to the \fBgroup\fR shell variable.
4596.TP 8
4597.B HOME
4598Equivalent to the \fBhome\fR shell variable.
4599.TP 8
4600.B HOST \fR(+)
4601Initialized to the name of the machine on which the shell
4602is running, as determined by the \fIgethostname\fR(2) system call.
4603.TP 8
4604.B HOSTTYPE \fR(+)
4605Initialized to the type of machine on which the shell
4606is running, as determined at compile time.  This variable is obsolete and
4607will be removed in a future version.
4608.TP 8
4609.B HPATH \fR(+)
4610A colon-separated list of directories in which the \fIrun-help\fR editor
4611command looks for command documentation.
4612.TP 8
4613.B LANG
4614Gives the preferred character environment.
4615See \fBNative Language System support\fR.
4616.TP 8
4617.B LC_CTYPE
4618If set, only ctype character handling is changed.
4619See \fBNative Language System support\fR.
4620.TP 8
4621.B LINES
4622The number of lines in the terminal.  See \fBTerminal management\fR.
4623.TP 8
4624.B LS_COLORS
4625The format of this variable is reminiscent of the \fBtermcap(5)\fR
4626file format; a colon-separated list of expressions of the form
4627"\fIxx=string\fR", where "\fIxx\fR" is a two-character variable name.  The
4628variables with their associated defaults are:
4629.PP
4630.RS +8
4631.RS +4
4632.PD 0
4633.TP 12
4634no      0
4635Normal (non-filename) text
4636.TP 12
4637fi      0
4638Regular file
4639.TP 12
4640di      01;34
4641Directory
4642.TP 12
4643ln      01;36
4644Symbolic link
4645.TP 12
4646pi      33
4647Named pipe (FIFO)
4648.TP 12
4649so      01;35
4650Socket
4651.TP 12
4652do      01;35
4653Door
4654.TP 12
4655bd      01;33
4656Block device
4657.TP 12
4658cd      01;32
4659Character device
4660.TP 12
4661ex      01;32
4662Executable file
4663.TP 12
4664mi      (none)
4665Missing file (defaults to fi)
4666.TP 12
4667or      (none)
4668Orphaned symbolic link (defaults to ln)
4669.TP 12
4670lc      ^[[
4671Left code
4672.TP 12
4673rc      m
4674Right code
4675.TP 12
4676ec      (none)
4677End code (replaces lc+no+rc)
4678.PD
4679.RE
4680.PP
4681You need to include only the variables you want to change from
4682the default.
4683.PP
4684File names can also be colorized based on filename extension.
4685This is specified in the \fBLS_COLORS\fR variable using the syntax
4686\fB"*ext=string"\fR.  For example, using ISO 6429 codes, to color
4687all C\-language source files blue you would specify \fB"*.c=34"\fR.
4688This would color all files ending in \fB.c\fR in blue (34) color.
4689.PP
4690Control characters can be written either in C\-style\-escaped
4691notation, or in stty\-like ^\-notation.  The C\-style notation
4692adds \fB^[\fR for Escape, \fB\_\fR for a normal space character,
4693and \fB?\fR for Delete.  In addition, the \fB^[\fR escape character
4694can be used to override the default interpretation of \fB^[\fR,
4695\fB^\fR, \fB:\fR and \fB=\fR.
4696.PP
4697Each file will be written as \fB<lc>\fR \fB<color-code>\fR
4698\fB<rc>\fR \fB<filename>\fR \fB<ec>\fR.  If the \fB<ec>\fR
4699code is undefined, the sequence \fB<lc>\fR \fB<no>
4700\fB<rc>\fR will be used instead.  This is generally more convenient
4701to use, but less general.  The left, right and end codes are
4702provided so you don't have to type common parts over and over
4703again and to support weird terminals; you will generally not
4704need to change them at all unless your terminal does not use
4705ISO 6429 color sequences but a different system.
4706.PP
4707If your terminal does use ISO 6429 color codes, you can
4708compose the type codes (i.e., all except the \fBlc\fR, \fBrc\fR,
4709and \fBec\fR codes) from numerical commands separated by semicolons.  The
4710most common commands are:
4711.PP
4712.RS +8
4713.PD 0
4714.TP 4
47150
4716to restore default color
4717.TP 4
47181
4719for brighter colors
4720.TP 4
47214
4722for underlined text
4723.TP 4
47245
4725for flashing text
4726.TP 4
472730
4728for black foreground
4729.TP 4
473031
4731for red foreground
4732.TP 4
473332
4734for green foreground
4735.TP 4
473633
4737for yellow (or brown) foreground
4738.TP 4
473934
4740for blue foreground
4741.TP 4
474235
4743for purple foreground
4744.TP 4
474536
4746for cyan foreground
4747.TP 4
474837
4749for white (or gray) foreground
4750.TP 4
475140
4752for black background
4753.TP 4
475441
4755for red background
4756.TP 4
475742
4758for green background
4759.TP 4
476043
4761for yellow (or brown) background
4762.TP 4
476344
4764for blue background
4765.TP 4
476645
4767for purple background
4768.TP 4
476946
4770for cyan background
4771.TP 4
477247
4773for white (or gray) background
4774.PD
4775.RE
4776.PP
4777Not all commands will work on all systems or display devices.
4778.PP
4779A few terminal programs do not recognize the default end code
4780properly.  If all text gets colorized after you do a directory
4781listing, try changing the \fBno\fR and \fBfi\fR codes from 0 to the
4782numerical codes for your standard fore- and background colors.
4783.RE
4784.TP 8
4785.B MACHTYPE \fR(+)
4786The machine type (microprocessor class or machine model), as determined at compile time.
4787.TP 8
4788.B NOREBIND \fR(+)
4789If set, printable characters are not rebound to \fIself-insert-command\fR.
4790See \fBNative Language System support\fR.
4791.TP 8
4792.B OSTYPE \fR(+)
4793The operating system, as determined at compile time.
4794.TP 8
4795.B PATH
4796A colon-separated list of directories in which to look for executables.
4797Equivalent to the \fBpath\fR shell variable, but in a different format.
4798.TP 8
4799.B PWD \fR(+)
4800Equivalent to the \fBcwd\fR shell variable, but not synchronized to it;
4801updated only after an actual directory change.
4802.TP 8
4803.B REMOTEHOST \fR(+)
4804The host from which the user has logged in remotely, if this is the case and
4805the shell is able to determine it.  Set only if the shell was so compiled;
4806see the \fBversion\fR shell variable.
4807.TP 8
4808.B SHLVL \fR(+)
4809Equivalent to the \fBshlvl\fR shell variable.
4810.TP 8
4811.B SYSTYPE \fR(+)
4812The current system type.  (Domain/OS only)
4813.TP 8
4814.B TERM
4815Equivalent to the \fBterm\fR shell variable.
4816.TP 8
4817.B TERMCAP
4818The terminal capability string.  See \fBTerminal management\fR.
4819.TP 8
4820.B USER
4821Equivalent to the \fBuser\fR shell variable.
4822.TP 8
4823.B VENDOR \fR(+)
4824The vendor, as determined at compile time.
4825.TP 8
4826.B VISUAL
4827The pathname to a default full-screen editor.
4828See also the \fBEDITOR\fR environment variable
4829and the \fIrun-fg-editor\fR editor command.
4830.SH FILES
4831.PD 0
4832.TP 16
4833.I /etc/csh.cshrc
4834Read first by every shell.
4835ConvexOS, Stellix and Intel use \fI/etc/cshrc\fR and
4836NeXTs use \fI/etc/cshrc.std\fR.
4837A/UX, AMIX, Cray and IRIX have no equivalent in \fIcsh\fR(1),
4838but read this file in \fItcsh\fR anyway.
4839Solaris 2.x does not have it either, but \fItcsh\fR reads \fI/etc/.cshrc\fR.  (+)
4840.TP 16
4841.I /etc/csh.login
4842Read by login shells after \fI/etc/csh.cshrc\fR.
4843ConvexOS, Stellix and Intel use \fI/etc/login\fR,
4844NeXTs use \fI/etc/login.std\fR, Solaris 2.x uses \fI/etc/.login\fR and
4845A/UX, AMIX, Cray and IRIX use \fI/etc/cshrc\fR.
4846.TP 16
4847.I ~/.tcshrc \fR(+)
4848Read by every shell after \fI/etc/csh.cshrc\fR or its equivalent.
4849.TP 16
4850.I ~/.cshrc
4851Read by every shell, if \fI~/.tcshrc\fR doesn't exist,
4852after \fI/etc/csh.cshrc\fR or its equivalent.
4853This manual uses `\fI~/.tcshrc\fR' to mean `\fI~/.tcshrc\fR or,
4854if \fI~/.tcshrc\fR is not found, \fI~/.cshrc\fR'.
4855.TP 16
4856.I ~/.history
4857Read by login shells after \fI~/.tcshrc\fR
4858if \fBsavehist\fR is set, but see also \fBhistfile\fR.
4859.TP 16
4860.I ~/.login
4861Read by login shells after \fI~/.tcshrc\fR or \fI~/.history\fR.
4862The shell may be compiled to read \fI~/.login\fR before instead of after
4863\fI~/.tcshrc\fR and \fI~/.history\fR; see the \fBversion\fR shell variable.
4864.TP 16
4865.I ~/.cshdirs \fR(+)
4866Read by login shells after \fI~/.login\fR
4867if \fBsavedirs\fR is set, but see also \fBdirsfile\fR.
4868.TP 16
4869.I /etc/csh.logout
4870Read by login shells at logout.
4871ConvexOS, Stellix and Intel use \fI/etc/logout\fR and
4872NeXTs use \fI/etc/logout.std\fR.
4873A/UX, AMIX, Cray and IRIX have no equivalent in \fIcsh\fR(1),
4874but read this file in \fItcsh\fR anyway.
4875Solaris 2.x does not have it either, but \fItcsh\fR reads \fI/etc/.logout\fR.  (+)
4876.TP 16
4877.I ~/.logout
4878Read by login shells at logout after \fI/etc/csh.logout\fR or its equivalent.
4879.TP 16
4880.I /bin/sh
4881Used to interpret shell scripts not starting with a `#'.
4882.TP 16
4883.I /tmp/sh*
4884Temporary file for `<<'.
4885.TP 16
4886.I /etc/passwd
4887Source of home directories for `~name' substitutions.
4888.PD
4889.PP
4890The order in which startup files are read may differ if the shell was so
4891compiled; see \fBStartup and shutdown\fR and the \fBversion\fR shell variable.
4892.SH "NEW FEATURES (+)"
4893This manual describes \fItcsh\fR as a single entity,
4894but experienced \fIcsh\fR(1) users will want to pay special attention to
4895\fItcsh\fR's new features.
4896.PP
4897A command-line editor, which supports GNU Emacs or \fIvi\fR(1)-style
4898key bindings.  See \fBThe command-line editor\fR and \fBEditor commands\fR.
4899.PP
4900Programmable, interactive word completion and listing.
4901See \fBCompletion and listing\fR and the \fIcomplete\fR and \fIuncomplete\fR
4902builtin commands.
4903.PP
4904\fBSpelling correction\fR (q.v.) of filenames, commands and variables.
4905.PP
4906\fBEditor commands\fR (q.v.) which perform other useful functions in the middle of
4907typed commands, including documentation lookup (\fIrun-help\fR),
4908quick editor restarting (\fIrun-fg-editor\fR) and
4909command resolution (\fIwhich-command\fR).
4910.PP
4911An enhanced history mechanism.  Events in the history list are time-stamped.
4912See also the \fIhistory\fR command and its associated shell variables,
4913the previously undocumented `#' event specifier and new modifiers
4914under \fBHistory substitution\fR,
4915the \fI*-history\fR, \fIhistory-search-*\fR, \fIi-search-*\fR, \fIvi-search-*\fR and
4916\fItoggle-literal-history\fR editor commands
4917and the \fBhistlit\fR shell variable.
4918.PP
4919Enhanced directory parsing and directory stack handling.
4920See the \fIcd\fR, \fIpushd\fR, \fIpopd\fR and \fIdirs\fR commands and their associated
4921shell variables, the description of \fBDirectory stack substitution\fR,
4922the \fBdirstack\fR, \fBowd\fR and \fBsymlinks\fR shell variables and
4923the \fInormalize-command\fR and \fInormalize-path\fR editor commands.
4924.PP
4925Negation in glob-patterns.  See \fBFilename substitution\fR.
4926.PP
4927New \fBFile inquiry operators\fR (q.v.) and a \fIfiletest\fR
4928builtin which uses them.
4929.PP
4930A variety of \fBAutomatic, periodic and timed events\fR (q.v.) including
4931scheduled events, special aliases, automatic logout and terminal locking,
4932command timing and watching for logins and logouts.
4933.PP
4934Support for the Native Language System
4935(see \fBNative Language System support\fR),
4936OS variant features
4937(see \fBOS variant support\fR and the \fBecho_style\fR shell variable)
4938and system-dependent file locations (see \fBFILES\fR).
4939.PP
4940Extensive terminal-management capabilities.  See \fBTerminal management\fR.
4941.PP
4942New builtin commands including \fIbuiltins\fR, \fIhup\fR, \fIls\-F\fR,
4943\fInewgrp\fR, \fIprintenv\fR, \fIwhich\fR and \fIwhere\fR (q.v.).
4944.PP
4945New variables that make useful information easily available to the shell.
4946See the \fBgid\fR, \fBloginsh\fR, \fBoid\fR, \fBshlvl\fR, \fBtcsh\fR,
4947\fBtty\fR, \fBuid\fR and \fBversion\fR shell variables and the \fBHOST\fR,
4948\fBREMOTEHOST\fR, \fBVENDOR\fR, \fBOSTYPE\fR and \fBMACHTYPE\fR environment
4949variables.
4950.PP
4951A new syntax for including useful information in the prompt string
4952(see \fBprompt\fR).
4953and special prompts for loops and spelling correction
4954(see \fBprompt2\fR and \fBprompt3\fR).
4955.PP
4956Read-only variables.  See \fBVariable substitution\fR.
4957.SH BUGS
4958When a suspended command is restarted, the shell prints the directory
4959it started in if this is different from the current directory.  This can
4960be misleading (i.e., wrong) as the job may have changed directories internally.
4961.PP
4962Shell builtin functions are not stoppable/restartable.  Command sequences
4963of the form `a ; b ; c' are also not handled gracefully when stopping is
4964attempted.  If you suspend `b', the shell will then immediately execute
4965`c'.  This is especially noticeable if this expansion results from an
4966\fIalias\fR.  It suffices to place the sequence of commands in ()'s to force it
4967to a subshell, i.e., `( a ; b ; c )'.
4968.PP
4969Control over tty output after processes are started is primitive; perhaps
4970this will inspire someone to work on a good virtual terminal interface.
4971In a virtual terminal interface much more interesting things could be
4972done with output control.
4973.PP
4974Alias substitution is most often used to clumsily simulate shell procedures;
4975shell procedures should be provided rather than aliases.
4976.PP
4977Commands within loops are not placed in the history
4978list.  Control structures should be parsed rather than being recognized as
4979built-in commands.  This would allow control commands to be placed anywhere,
4980to be combined with `|', and to be used with `&' and `;' metasyntax.
4981.PP
4982\fIforeach\fR doesn't ignore here documents when looking for its \fIend\fR.
4983.PP
4984It should be possible to use the `:' modifiers on the output of command
4985substitutions.
4986.PP
4987The screen update for lines longer than the screen width is very poor
4988if the terminal cannot move the cursor up (i.e., terminal type `dumb').
4989.PP
4990\fBHPATH\fR and \fBNOREBIND\fR don't need to be environment variables.
4991.PP
4992Glob-patterns which do not use `?', `*' or `[]' or which use `{}' or `~'
4993are not negated correctly.
4994.PP
4995The single-command form of \fIif\fR does output redirection even if
4996the expression is false and the command is not executed.
4997.PP
4998\fIls\-F\fR includes file identification characters when sorting filenames
4999and does not handle control characters in filenames well.  It cannot be
5000interrupted.
5001.PP
5002Command substitution supports multiple commands and conditions, but not
5003cycles or backward \fIgoto\fRs.
5004.PP
5005Report bugs at http://bugs.gw.com/, preferably with fixes.  If you want to
5006help maintain and test tcsh, send mail to tcsh-request@mx.gw.com with the
5007text `subscribe tcsh' on a line by itself in the body.
5008.SH THE T IN TCSH
5009In 1964, DEC produced the PDP-6.  The PDP-10 was a later re-implementation.  It
5010was re-christened the DECsystem-10 in 1970 or so when DEC brought out the
5011second model, the KI10.
5012.PP
5013TENEX was created at Bolt, Beranek & Newman (a Cambridge, Massachusetts
5014think tank) in
50151972 as an experiment in demand-paged virtual memory operating systems.  They
5016built a new pager for the DEC PDP-10 and created the OS to go with it.  It was
5017extremely successful in academia.
5018.PP
5019In 1975, DEC brought out a new model of the PDP-10, the KL10; they intended to
5020have only a version of TENEX, which they had licensed from BBN, for the new
5021box.  They called their version TOPS-20 (their capitalization is trademarked).
5022A lot of TOPS-10 users (`The OPerating System for PDP-10') objected; thus DEC
5023found themselves supporting two incompatible systems on the same hardware--but
5024then there were 6 on the PDP-11!
5025.PP
5026TENEX, and TOPS-20 to version 3, had command completion
5027via a user-code-level subroutine library called ULTCMD.  With version 3, DEC
5028moved all that capability and more into the monitor (`kernel' for you Unix
5029types), accessed by the COMND% JSYS (`Jump to SYStem' instruction, the
5030supervisor call mechanism [are my IBM roots also showing?]).
5031.PP
5032The creator of tcsh was impressed by this feature and several others of TENEX
5033and TOPS-20, and created a version of csh which mimicked them.
5034.SH LIMITATIONS
5035Words can be no longer than 1024 characters.
5036.PP
5037The system limits argument lists to 10240 characters.
5038.PP
5039The number of arguments to a command which involves filename expansion is
5040limited to 1/6th the number of characters allowed in an argument list.
5041.PP
5042Command substitutions may substitute no more characters than are allowed in
5043an argument list.
5044.PP
5045To detect looping, the shell restricts the number of \fIalias\fR
5046substitutions on a single line to 20.
5047.SH "SEE ALSO"
5048csh(1), emacs(1), ls(1), newgrp(1), sh(1), setpath(1), stty(1), su(1),
5049tset(1), vi(1), x(1), access(2), execve(2), fork(2), killpg(2),
5050pipe(2), setrlimit(2), sigvec(2), stat(2), umask(2), vfork(2), wait(2),
5051malloc(3), setlocale(3), tty(4), a.out(5), termcap(5), environ(7),
5052termio(7), Introduction to the C Shell
5053.SH VERSION
5054This manual documents tcsh 6.14.00 (Astron) 2005-03-25.
5055.SH AUTHORS
5056.PD 0
5057.TP 2
5058William Joy
5059Original author of \fIcsh\fR(1)
5060.TP 2
5061J.E. Kulp, IIASA, Laxenburg, Austria
5062Job control and directory stack features
5063.TP 2
5064Ken Greer, HP Labs, 1981
5065File name completion
5066.TP 2
5067Mike Ellis, Fairchild, 1983
5068Command name recognition/completion
5069.TP 2
5070Paul Placeway, Ohio State CIS Dept., 1983-1993
5071Command line editor, prompt routines, new glob syntax and numerous fixes
5072and speedups
5073.TP 2
5074Karl Kleinpaste, CCI 1983-4
5075Special aliases, directory stack extraction stuff, login/logout watch,
5076scheduled events, and the idea of the new prompt format
5077.TP 2
5078Rayan Zachariassen, University of Toronto, 1984
5079\fIls\-F\fR and \fIwhich\fR builtins and numerous bug fixes, modifications
5080and speedups
5081.TP 2
5082Chris Kingsley, Caltech
5083Fast storage allocator routines
5084.TP 2
5085Chris Grevstad, TRW, 1987
5086Incorporated 4.3BSD \fIcsh\fR into \fItcsh\fR
5087.TP 2
5088Christos S. Zoulas, Cornell U. EE Dept., 1987-94
5089Ports to HPUX, SVR2 and SVR3, a SysV version of getwd.c, SHORT_STRINGS support
5090and a new version of sh.glob.c
5091.TP 2
5092James J Dempsey, BBN, and Paul Placeway, OSU, 1988
5093A/UX port
5094.TP 2
5095Daniel Long, NNSC, 1988
5096\fBwordchars\fR
5097.TP 2
5098Patrick Wolfe, Kuck and Associates, Inc., 1988
5099\fIvi\fR mode cleanup
5100.TP 2
5101David C Lawrence, Rensselaer Polytechnic Institute, 1989
5102\fBautolist\fR and ambiguous completion listing
5103.TP 2
5104Alec Wolman, DEC, 1989
5105Newlines in the prompt
5106.TP 2
5107Matt Landau, BBN, 1989
5108\fI~/.tcshrc\fR
5109.TP 2
5110Ray Moody, Purdue Physics, 1989
5111Magic space bar history expansion
5112.TP 2
5113Mordechai ????, Intel, 1989
5114printprompt() fixes and additions
5115.TP 2
5116Kazuhiro Honda, Dept. of Computer Science, Keio University, 1989
5117Automatic spelling correction and \fBprompt3\fR
5118.TP 2
5119Per Hedeland, Ellemtel, Sweden, 1990-
5120Various bugfixes, improvements and manual updates
5121.TP 2
5122Hans J. Albertsson (Sun Sweden)
5123\fBampm\fR, \fIsettc\fR and \fItelltc\fR
5124.TP 2
5125Michael Bloom
5126Interrupt handling fixes
5127.TP 2
5128Michael Fine, Digital Equipment Corp
5129Extended key support
5130.TP 2
5131Eric Schnoebelen, Convex, 1990
5132Convex support, lots of \fIcsh\fR bug fixes,
5133save and restore of directory stack
5134.TP 2
5135Ron Flax, Apple, 1990
5136A/UX 2.0 (re)port
5137.TP 2
5138Dan Oscarsson, LTH Sweden, 1990
5139NLS support and simulated NLS support for non NLS sites, fixes
5140.TP 2
5141Johan Widen, SICS Sweden, 1990
5142\fBshlvl\fR, Mach support, \fIcorrect-line\fR, 8-bit printing
5143.TP 2
5144Matt Day, Sanyo Icon, 1990
5145POSIX termio support, SysV limit fixes
5146.TP 2
5147Jaap Vermeulen, Sequent, 1990-91
5148Vi mode fixes, expand-line, window change fixes, Symmetry port
5149.TP 2
5150Martin Boyer, Institut de recherche d'Hydro-Quebec, 1991
5151\fBautolist\fR beeping options, modified the history search to search for
5152the whole string from the beginning of the line to the cursor.
5153.TP 2
5154Scott Krotz, Motorola, 1991
5155Minix port
5156.TP 2
5157David Dawes, Sydney U. Australia, Physics Dept., 1991
5158SVR4 job control fixes
5159.TP 2
5160Jose Sousa, Interactive Systems Corp., 1991
5161Extended \fIvi\fR fixes and \fIvi\fR delete command
5162.TP 2
5163Marc Horowitz, MIT, 1991
5164ANSIfication fixes, new exec hashing code, imake fixes, \fIwhere\fR
5165.TP 2
5166Bruce Sterling Woodcock, sterling@netcom.com, 1991-1995
5167ETA and Pyramid port, Makefile and lint fixes, \fBignoreeof\fR=n addition, and
5168various other portability changes and bug fixes
5169.TP 2
5170Jeff Fink, 1992
5171\fIcomplete-word-fwd\fR and \fIcomplete-word-back\fR
5172.TP 2
5173Harry C. Pulley, 1992
5174Coherent port
5175.TP 2
5176Andy Phillips, Mullard Space Science Lab U.K., 1992
5177VMS-POSIX port
5178.TP 2
5179Beto Appleton, IBM Corp., 1992
5180Walking process group fixes, \fIcsh\fR bug fixes,
5181POSIX file tests, POSIX SIGHUP
5182.TP 2
5183Scott Bolte, Cray Computer Corp., 1992
5184CSOS port
5185.TP 2
5186Kaveh R. Ghazi, Rutgers University, 1992
5187Tek, m88k, Titan and Masscomp ports and fixes.  Added autoconf support.
5188.TP 2
5189Mark Linderman, Cornell University, 1992
5190OS/2 port
5191.TP 2
5192Mika Liljeberg, liljeber@kruuna.Helsinki.FI, 1992
5193Linux port
5194.TP 2
5195Tim P. Starrin, NASA Langley Research Center Operations, 1993
5196Read-only variables
5197.TP 2
5198Dave Schweisguth, Yale University, 1993-4
5199New man page and tcsh.man2html
5200.TP 2
5201Larry Schwimmer, Stanford University, 1993
5202AFS and HESIOD patches
5203.TP 2
5204Luke Mewburn, RMIT University, 1994-6
5205Enhanced directory printing in prompt,
5206added \fBellipsis\fR and \fBrprompt\fR.
5207.TP 2
5208Edward Hutchins, Silicon Graphics Inc., 1996
5209Added implicit cd.
5210.TP 2
5211Martin Kraemer, 1997
5212Ported to Siemens Nixdorf EBCDIC machine
5213.TP 2
5214Amol Deshpande, Microsoft, 1997
5215Ported to WIN32 (Windows/95 and Windows/NT); wrote all the missing library
5216and message catalog code to interface to Windows.
5217.TP 2
5218Taga Nayuta, 1998
5219Color ls additions.
5220.PD
5221.PP
5222.SH "THANKS TO"
5223Bryan Dunlap, Clayton Elwell, Karl Kleinpaste, Bob Manson, Steve Romig,
5224Diana Smetters, Bob Sutterfield, Mark Verber, Elizabeth Zwicky and all
5225the other people at Ohio State for suggestions and encouragement
5226.PP
5227All the people on the net, for putting up with,
5228reporting bugs in, and suggesting new additions to each and every version
5229.PP
5230Richard M. Alderson III, for writing the `T in tcsh' section
Note: See TracBrowser for help on using the repository browser.