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