Import tcsh-6.17.00
[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 "10 July 2009" "Astron 6.17.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\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 `There are suspended jobs.' You may use the \fIjobs\fR command to
1898 see what they are.  If you do this or immediately try to exit again, the shell
1899 will 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 \fIcommand\fR invoked from `...` version has additional environment
2417 variable set, the variable name is \%\fBCOMMAND_LINE\fR\% and
2418 contains (as its name indicates) contents of the current (already
2419 typed in) command line. One can examine and use contents of the
2420 \%\fBCOMMAND_LINE\fR\% variable in her custom script to build more
2421 sophisticated completions (see completion for svn(1) included in
2422 this package).
2423 .PP
2424 Now for some examples.  Some commands take only directories as arguments,
2425 so there's no point completing plain files.
2426 .IP "" 4
2427 > complete cd 'p/1/d/'
2428 .PP
2429 completes only the first word following `cd' (`p/1') with a directory.
2430 \fBp\fR-type completion can also be used to narrow down command completion:
2431 .IP "" 4
2432 > co[^D]
2433 .br
2434 complete compress
2435 .br
2436 > complete \-co* 'p/0/(compress)/'
2437 .br
2438 > co[^D]
2439 .br
2440 > compress
2441 .PP
2442 This completion completes commands (words in position 0, `p/0')
2443 which begin with `co' (thus matching `co*') to `compress' (the only
2444 word in the list).
2445 The leading `\-' indicates that this completion is to be used with only
2446 ambiguous commands.
2447 .IP "" 4
2448 > complete find 'n/\-user/u/'
2449 .PP
2450 is an example of \fBn\fR-type completion.  Any word following `find' and
2451 immediately following `\-user' is completed from the list of users.
2452 .IP "" 4
2453 > complete cc 'c/\-I/d/'
2454 .PP
2455 demonstrates \fBc\fR-type completion.  Any word following `cc' and beginning
2456 with `\-I' is completed as a directory.  `\-I' is not taken as part of the
2457 directory because we used lowercase \fBc\fR.
2458 .PP
2459 Different \fIlist\fRs are useful with different commands.
2460 .IP "" 4
2461 > complete alias 'p/1/a/'
2462 .br
2463 > complete man 'p/*/c/'
2464 .br
2465 > complete set 'p/1/s/'
2466 .br
2467 > complete true 'p/1/x:Truth has no options./'
2468 .PP
2469 These complete words following `alias' with aliases, `man' with commands,
2470 and `set' with shell variables.
2471 `true' doesn't have any options, so \fBx\fR does nothing when completion
2472 is attempted and prints `Truth has no options.' when completion choices are listed.
2473 .PP
2474 Note that the \fIman\fR example, and several other examples below, could
2475 just as well have used 'c/*' or 'n/*' as 'p/*'.
2476 .PP
2477 Words can be completed from a variable evaluated at completion time,
2478 .IP "" 4
2479 > complete ftp 'p/1/$hostnames/'
2480 .br
2481 > set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu)
2482 .br
2483 > ftp [^D]
2484 .br
2485 rtfm.mit.edu tesla.ee.cornell.edu
2486 .br
2487 > ftp [^C]
2488 .br
2489 > set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net)
2490 .br
2491 > ftp [^D]
2492 .br
2493 rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net
2494 .PP
2495 or from a command run at completion time:
2496 .IP "" 4
2497 > complete kill 'p/*/`ps | awk \\{print\\ \\$1\\}`/'
2498 .br
2499 > kill \-9 [^D]
2500 .br
2501 23113 23377 23380 23406 23429 23529 23530 PID
2502 .PP
2503 Note that the \fIcomplete\fR command does not itself quote its arguments,
2504 so the braces, space and `$' in `{print $1}' must be quoted explicitly.
2505 .PP
2506 One command can have multiple completions:
2507 .IP "" 4
2508 > complete dbx 'p/2/(core)/' 'p/*/c/'
2509 .PP
2510 completes the second argument to `dbx' with the word `core' and all other
2511 arguments with commands.  Note that the positional completion is specified
2512 before the next-word completion.
2513 Because completions are evaluated from left to right, if
2514 the next-word completion were specified first it would always match
2515 and the positional completion would never be executed.  This is a
2516 common mistake when defining a completion.
2517 .PP
2518 The \fIselect\fR pattern is useful when a command takes files with only
2519 particular forms as arguments.  For example,
2520 .IP "" 4
2521 > complete cc 'p/*/f:*.[cao]/'
2522 .PP
2523 completes `cc' arguments to files ending in only `.c', `.a', or `.o'.
2524 \fIselect\fR can also exclude files, using negation of a glob-pattern as
2525 described under \fBFilename substitution\fR.  One might use
2526 .IP "" 4
2527 > complete rm 'p/*/f:^*.{c,h,cc,C,tex,1,man,l,y}/'
2528 .PP
2529 to exclude precious source code from `rm' completion.  Of course, one
2530 could still type excluded names manually or override the completion
2531 mechanism using the \fIcomplete-word-raw\fR or \fIlist-choices-raw\fR
2532 editor commands (q.v.).
2533 .PP
2534 The `C', `D', `F' and `T' \fIlist\fRs are like `c', `d', `f' and `t'
2535 respectively, but they use the \fIselect\fR argument in a different way: to
2536 restrict completion to files beginning with a particular path prefix.  For
2537 example, the Elm mail program uses `=' as an abbreviation for one's mail
2538 directory.  One might use
2539 .IP "" 4
2540 > complete elm c@=@F:$HOME/Mail/@
2541 .PP
2542 to complete `elm \-f =' as if it were `elm \-f ~/Mail/'.  Note that we used `@'
2543 instead of `/' to avoid confusion with the \fIselect\fR argument, and we used
2544 `$HOME' instead of `~' because home directory substitution works at only the
2545 beginning of a word.
2546 .PP
2547 \fIsuffix\fR is used to add a nonstandard suffix
2548 (not space or `/' for directories) to completed words.
2549 .IP "" 4
2550 > complete finger 'c/*@/$hostnames/' 'p/1/u/@'
2551 .PP
2552 completes arguments to `finger' from the list of users, appends an `@',
2553 and then completes after the `@' from the `hostnames' variable.  Note
2554 again the order in which the completions are specified.
2555 .PP
2556 Finally, here's a complex example for inspiration:
2557 .IP "" 4
2558 > complete find \\
2559 .br
2560 \&'n/\-name/f/' 'n/\-newer/f/' 'n/\-{,n}cpio/f/' \e
2561 .br
2562 \'n/\-exec/c/' 'n/\-ok/c/' 'n/\-user/u/' \e
2563 .br
2564 \&'n/\-group/g/' 'n/\-fstype/(nfs 4.2)/' \e
2565 .br
2566 \&'n/\-type/(b c d f l p s)/' \e
2567 .br
2568 \'c/\-/(name newer cpio ncpio exec ok user \e
2569 .br
2570 group fstype type atime ctime depth inum \e
2571 .br
2572 ls mtime nogroup nouser perm print prune \e
2573 .br
2574 size xdev)/' \e
2575 .br
2576 \&'p/*/d/'
2577 .PP
2578 This completes words following `\-name', `\-newer', `\-cpio' or `ncpio'
2579 (note the pattern which matches both) to files,
2580 words following `\-exec' or `\-ok' to commands, words following `user'
2581 and `group' to users and groups respectively
2582 and words following `\-fstype' or `\-type' to members of the
2583 given lists.  It also completes the switches themselves from the given list
2584 (note the use of \fBc\fR-type completion)
2585 and completes anything not otherwise completed to a directory.  Whew.
2586 .PP
2587 Remember that programmed completions are ignored if the word being completed
2588 is a tilde substitution (beginning with `~') or a variable (beginning with `$').
2589 \fIcomplete\fR is an experimental feature, and the syntax may change
2590 in future versions of the shell.
2591 See also the \fIuncomplete\fR builtin command.
2592 .RE
2593 .TP 8
2594 .B continue
2595 Continues execution of the nearest enclosing \fIwhile\fR or \fIforeach\fR.
2596 The rest of the commands on the current line are executed.
2597 .TP 8
2598 .B default:
2599 Labels the default case in a \fIswitch\fR statement.
2600 It should come after all \fIcase\fR labels.
2601 .PP
2602 .B dirs \fR[\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR]
2603 .br
2604 .B dirs \-S\fR|\fB\-L \fR[\fIfilename\fR] (+)
2605 .PD 0
2606 .TP 8
2607 .B dirs \-c \fR(+)
2608 The first form prints the directory stack.  The top of the stack is at the
2609 left and the first directory in the stack is the current directory.
2610 With \fB\-l\fR, `~' or `~\fIname\fP' in the output is expanded explicitly
2611 to \fBhome\fR or the pathname of the home directory for user \fIname\fP.  (+)
2612 With \fB\-n\fR, entries are wrapped before they reach the edge of the screen.  (+)
2613 With \fB\-v\fR, entries are printed one per line, preceded by their stack positions.  (+)
2614 If more than one of \fB\-n\fR or \fB\-v\fR is given, \fB\-v\fR takes precedence.
2615 \fB\-p\fR is accepted but does nothing.
2616 .PD
2617 .RS +8
2618 .PP
2619 With \fB\-S\fR, the second form saves the directory stack to \fIfilename\fR
2620 as a series of \fIcd\fR and \fIpushd\fR commands.
2621 With \fB\-L\fR, the shell sources \fIfilename\fR, which is presumably
2622 a directory stack file saved by the \fB\-S\fR option or the \fBsavedirs\fR
2623 mechanism.
2624 In either case, \fBdirsfile\fR is used if \fIfilename\fR is not given and
2625 \fI~/.cshdirs\fR is used if \fBdirsfile\fR is unset.
2626 .PP
2627 Note that login shells do the equivalent of `dirs \-L' on startup
2628 and, if \fBsavedirs\fR is set, `dirs \-S' before exiting.
2629 Because only \fI~/.tcshrc\fR is normally sourced before \fI~/.cshdirs\fR,
2630 \fBdirsfile\fR should be set in \fI~/.tcshrc\fR rather than \fI~/.login\fR.
2631 .PP
2632 The last form clears the directory stack.
2633 .RE
2634 .TP 8
2635 .B echo \fR[\fB\-n\fR] \fIword\fR ...
2636 Writes each \fIword\fR to the shell's standard
2637 output, separated by spaces and terminated with a newline.
2638 The \fBecho_style\fR shell variable may be set to emulate (or not) the flags and escape
2639 sequences of the BSD and/or System V versions of \fIecho\fR; see \fIecho\fR(1).
2640 .TP 8
2641 .B echotc \fR[\fB\-sv\fR] \fIarg\fR ... (+)
2642 Exercises the terminal capabilities (see \fItermcap\fR(5)) in \fIargs\fR.
2643 For example, 'echotc home' sends the cursor to the home position,
2644 \&'echotc cm 3 10' sends it to column 3 and row 10, and
2645 \&'echotc ts 0; echo "This is a test."; echotc fs' prints "This is a test."
2646 in the status line.
2647 .RS +8
2648 .PP
2649 If \fIarg\fR is 'baud', 'cols', 'lines', 'meta' or 'tabs', prints the
2650 value of that capability ("yes" or "no" indicating that the terminal does
2651 or does not have that capability).  One might use this to make the output
2652 from a shell script less verbose on slow terminals, or limit command
2653 output to the number of lines on the screen:
2654 .IP "" 4
2655 > set history=`echotc lines`
2656 .br
2657 > @ history\-\-
2658 .PP
2659 Termcap strings may contain wildcards which will not echo correctly.
2660 One should use double quotes when setting a shell variable to a terminal
2661 capability string, as in the following example that places the date in
2662 the status line:
2663 .IP "" 4
2664 > set tosl="`echotc ts 0`"
2665 .br
2666 > set frsl="`echotc fs`"
2667 .br
2668 > echo \-n "$tosl";date; echo \-n "$frsl"
2669 .PP
2670 With \fB\-s\fR, nonexistent capabilities return the empty string rather
2671 than causing an error.
2672 With \fB\-v\fR, messages are verbose.
2673 .RE
2674 .PP
2675 .B else
2676 .br
2677 .B end
2678 .br
2679 .B endif
2680 .PD 0
2681 .TP 8
2682 .B endsw
2683 See the description of the \fIforeach\fR, \fIif\fR, \fIswitch\fR, and
2684 \fIwhile\fR statements below.
2685 .PD
2686 .TP 8
2687 .B eval \fIarg\fR ...
2688 Treats the arguments as input to the
2689 shell and executes the resulting command(s) in the context
2690 of the current shell.  This is usually used to execute commands
2691 generated as the result of command or variable substitution,
2692 because parsing occurs before these substitutions.
2693 See \fItset\fR(1) for a sample use of \fIeval\fR.
2694 .TP 8
2695 .B exec \fIcommand\fR
2696 Executes the specified command in place of the current shell.
2697 .TP 8
2698 .B exit \fR[\fIexpr\fR]
2699 The shell exits either with the value of the specified \fIexpr\fR
2700 (an expression, as described under \fBExpressions\fR)
2701 or, without \fIexpr\fR, with the value 0.
2702 .TP 8
2703 .B fg \fR[\fB%\fIjob\fR ...]
2704 Brings the specified jobs (or, without arguments, the current job)
2705 into the foreground, continuing each if it is stopped.
2706 \fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
2707 under \fBJobs\fR.
2708 See also the \fIrun-fg-editor\fR editor command.
2709 .TP 8
2710 .B filetest \-\fIop file\fR ... (+)
2711 Applies \fIop\fR (which is a file inquiry operator as described under
2712 \fBFile inquiry operators\fR) to each \fIfile\fR and returns the results as a
2713 space-separated list.
2714 .PP
2715 .B foreach \fIname \fB(\fIwordlist\fB)
2716 .br
2717 \&...
2718 .PD 0
2719 .TP 8
2720 .B end
2721 Successively sets the variable \fIname\fR to each member of
2722 \fIwordlist\fR and executes the sequence of commands between this command
2723 and the matching \fIend\fR.  (Both \fIforeach\fR and \fIend\fR
2724 must appear alone on separate lines.)  The builtin command
2725 \fIcontinue\fR may be used to continue the loop prematurely and
2726 the builtin command \fIbreak\fR to terminate it prematurely.
2727 When this command is read from the terminal, the loop is read once
2728 prompting with `foreach? ' (or \fBprompt2\fR) before any statements in
2729 the loop are executed.  If you make a mistake typing in a
2730 loop at the terminal you can rub it out.
2731 .PD
2732 .TP 8
2733 .B getspath \fR(+)
2734 Prints the system execution path.  (TCF only)
2735 .TP 8
2736 .B getxvers \fR(+)
2737 Prints the experimental version prefix.  (TCF only)
2738 .TP 8
2739 .B glob \fIwordlist
2740 Like \fIecho\fR, but the `-n' parameter is not recognized and words are
2741 delimited by null characters in the output.  Useful for
2742 programs which wish to use the shell to filename expand a list of words.
2743 .TP 8
2744 .B goto \fIword
2745 \fIword\fR is filename and command-substituted to
2746 yield a string of the form `label'.  The shell rewinds its
2747 input as much as possible, searches for a line of the
2748 form `label:', possibly preceded by blanks or tabs, and
2749 continues execution after that line.
2750 .TP 8
2751 .B hashstat
2752 Prints a statistics line indicating how effective the
2753 internal hash table has been at locating commands (and avoiding
2754 \fIexec\fR's).  An \fIexec\fR is attempted for each component of the
2755 \fBpath\fR where the hash function indicates a possible hit, and
2756 in each component which does not begin with a `/'.
2757 .IP
2758 On machines without \fIvfork\fR(2), prints only the number and size of
2759 hash buckets.
2760 .PP
2761 .B history \fR[\fB\-hTr\fR] [\fIn\fR]
2762 .br
2763 .B history \-S\fR|\fB\-L|\fB\-M \fR[\fIfilename\fR] (+)
2764 .PD 0
2765 .TP 8
2766 .B history \-c \fR(+)
2767 The first form prints the history event list.
2768 If \fIn\fR is given only the \fIn\fR most recent events are printed or saved.
2769 With \fB\-h\fR, the history list is printed without leading numbers.  If
2770 \fB-T\fR is specified, timestamps are printed also in comment form.
2771 (This can be used to
2772 produce files suitable for loading with 'history \-L' or 'source \-h'.)
2773 With \fB\-r\fR, the order of printing is most recent
2774 first rather than oldest first.
2775 .PD
2776 .RS +8
2777 .PP
2778 With \fB\-S\fR, the second form saves the history list to \fIfilename\fR.
2779 If the first word of the \fBsavehist\fR shell variable is set to a
2780 number, at most that many lines are saved.  If the second word of
2781 \fBsavehist\fR is set to `merge', the history list is merged with the
2782 existing history file instead of replacing it (if there is one) and
2783 sorted by time stamp.  (+) Merging is intended for an environment like
2784 the X Window System
2785 with several shells in simultaneous use.  Currently it succeeds
2786 only when the shells quit nicely one after another.
2787 .PP
2788 With \fB\-L\fR, the shell appends \fIfilename\fR, which is presumably a
2789 history list saved by the \fB\-S\fR option or the \fBsavehist\fR mechanism,
2790 to the history list.
2791 \fB\-M\fR is like \fB\-L\fR, but the contents of \fIfilename\fR are merged
2792 into the history list and sorted by timestamp.
2793 In either case, \fBhistfile\fR is used if \fIfilename\fR is not given and
2794 \fI~/.history\fR is used if \fBhistfile\fR is unset.
2795 `history \-L' is exactly like 'source \-h' except that it does not require a
2796 filename.
2797 .PP
2798 Note that login shells do the equivalent of `history \-L' on startup
2799 and, if \fBsavehist\fR is set, `history \-S' before exiting.
2800 Because only \fI~/.tcshrc\fR is normally sourced before \fI~/.history\fR,
2801 \fBhistfile\fR should be set in \fI~/.tcshrc\fR rather than \fI~/.login\fR.
2802 .PP
2803 If \fBhistlit\fR is set, the first and second forms print and save the literal
2804 (unexpanded) form of the history list.
2805 .PP
2806 The last form clears the history list.
2807 .RE
2808 .TP 8
2809 .B hup \fR[\fIcommand\fR] \fR(+)
2810 With \fIcommand\fR, runs \fIcommand\fR such that it will exit on a hangup
2811 signal and arranges for the shell to send it a hangup signal when the shell
2812 exits.
2813 Note that commands may set their own response to hangups, overriding \fIhup\fR.
2814 Without an argument (allowed in only a shell script), causes the shell to
2815 exit on a hangup for the remainder of the script.
2816 See also \fBSignal handling\fR and the \fInohup\fR builtin command.
2817 .TP 8
2818 .B if (\fIexpr\fB) \fIcommand
2819 If \fIexpr\fR (an expression, as described under \fBExpressions\fR)
2820 evaluates true, then \fIcommand\fR is executed.
2821 Variable substitution on \fIcommand\fR happens early, at the same time it
2822 does for the rest of the \fIif\fR command.
2823 \fIcommand\fR must be a simple command, not an alias, a pipeline, a command list
2824 or a parenthesized command list, but it may have arguments.
2825 Input/output redirection occurs even if \fIexpr\fR is
2826 false and \fIcommand\fR is thus \fInot\fR executed; this is a bug.
2827 .PP
2828 .B if (\fIexpr\fB) then
2829 .br
2830 \&...
2831 .br
2832 .B else if (\fIexpr2\fB) then
2833 .br
2834 \&...
2835 .br
2836 .B else
2837 .br
2838 \&...
2839 .PD 0
2840 .TP 8
2841 .B endif
2842 If the specified \fIexpr\fR is true then the commands to the
2843 first \fIelse\fR are executed; otherwise if \fIexpr2\fR is true then
2844 the commands to the second \fIelse\fR are executed, etc.  Any
2845 number of \fIelse-if\fR pairs are possible; only one \fIendif\fR is
2846 needed.  The \fIelse\fR part is likewise optional.  (The words
2847 \fIelse\fR and \fIendif\fR must appear at the beginning of input lines;
2848 the \fIif\fR must appear alone on its input line or after an
2849 \fIelse\fR.)
2850 .PD
2851 .TP 8
2852 .B inlib \fIshared-library\fR ... (+)
2853 Adds each \fIshared-library\fR to the current environment.  There is no way
2854 to remove a shared library.  (Domain/OS only)
2855 .TP 8
2856 .B jobs \fR[\fB\-l\fR]
2857 Lists the active jobs.  With \fB\-l\fR, lists process
2858 IDs in addition to the normal information.  On TCF systems, prints
2859 the site on which each job is executing.
2860 .PP
2861 .PD 0
2862 .TP 8
2863 .B kill \fR[\fB\-s \fIsignal\fR] \fB%\fIjob\fR|\fIpid\fR ...
2864 .PD 0
2865 .TP 8
2866 .B kill \-l
2867 The first and second forms sends the specified \fIsignal\fR (or, if none
2868 is given, the TERM (terminate) signal) to the specified jobs or processes.
2869 \fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
2870 under \fBJobs\fR.
2871 Signals are either given by number or by name (as given in
2872 \fI/usr/include/signal.h\fR, stripped of the prefix `SIG').
2873 There is no default \fIjob\fR; saying just `kill' does not send a signal
2874 to the current job.  If the signal being sent is TERM (terminate)
2875 or HUP (hangup), then the job or process is sent a
2876 CONT (continue) signal as well.
2877 The third form lists the signal names.
2878 .PD
2879 .TP 8
2880 .B limit \fR[\fB\-h\fR] [\fIresource\fR [\fImaximum-use\fR]]
2881 Limits the consumption by the current process and each
2882 process it creates to not individually exceed \fImaximum-use\fR on
2883 the specified \fIresource\fR.  If no \fImaximum-use\fR is given, then
2884 the current limit is printed; if no \fIresource\fR is given, then
2885 all limitations are given.  If the \fB\-h\fR flag is given, the
2886 hard limits are used instead of the current limits.  The
2887 hard limits impose a ceiling on the values of the current
2888 limits.  Only the super-user may raise the hard limits, but
2889 a user may lower or raise the current limits within the legal range.
2890 .RS +8
2891 .PP
2892 Controllable resources currently include (if supported by the OS):
2893 .TP
2894 \fIcputime\fR
2895 the maximum number of cpu-seconds to be used by each process
2896 .TP
2897 \fIfilesize\fR
2898 the largest single file which can be created
2899 .TP
2900 \fIdatasize\fR
2901 the maximum growth of the data+stack region via sbrk(2) beyond
2902 the end of the program text
2903 .TP
2904 \fIstacksize\fR
2905 the maximum size of the automatically-extended stack region
2906 .TP
2907 \fIcoredumpsize\fR
2908 the size of the largest core dump that will be created
2909 .TP
2910 \fImemoryuse\fR
2911 the maximum amount of physical memory a process
2912 may have allocated to it at a given time
2913 .TP
2914 \fIheapsize\fR
2915 the maximum amount of memory a process
2916 may allocate per \fIbrk()\fR system call
2917 .TP
2918 \fIdescriptors\fR or \fIopenfiles\fR
2919 the maximum number of open files for this process
2920 .TP
2921 \fIconcurrency\fR
2922 the maximum number of threads for this process
2923 .TP
2924 \fImemorylocked\fR
2925 the maximum size which a process may lock into memory using mlock(2)
2926 .TP
2927 \fImaxproc\fR
2928 the maximum number of simultaneous processes for this user id
2929 .TP
2930 \fIsbsize\fR
2931 the maximum size of socket buffer usage for this user
2932 .TP 
2933 \fIswapsize\fR 
2934 the maximum amount of swap space reserved or used for this user 
2935 .PP
2936 \fImaximum-use\fR may be given as a (floating point or
2937 integer) number followed by a scale factor.  For all limits
2938 other than \fIcputime\fR the default scale is `k' or `kilobytes'
2939 (1024 bytes); a scale factor of `m' or `megabytes' may also
2940 be used.  For \fIcputime\fR the default scaling is `seconds',
2941 while `m' for minutes or `h' for hours, or a time of the
2942 form `mm:ss' giving minutes and seconds may be used.
2943 .PP
2944 For both \fIresource\fR names and scale factors, unambiguous
2945 prefixes of the names suffice.
2946 .RE
2947 .TP 8
2948 .B log \fR(+)
2949 Prints the \fBwatch\fR shell variable and reports on each user indicated
2950 in \fBwatch\fR who is logged in, regardless of when they last logged in.
2951 See also \fIwatchlog\fR.
2952 .TP 8
2953 .B login
2954 Terminates a login shell, replacing it with an instance of
2955 \fI/bin/login.\fR This is one way to log off, included for
2956 compatibility with \fIsh\fR(1).
2957 .TP 8
2958 .B logout
2959 Terminates a login shell.  Especially useful if \fBignoreeof\fR is set.
2960 .TP 8
2961 .B ls\-F \fR[\-\fIswitch\fR ...] [\fIfile\fR ...] (+)
2962 Lists files like `ls \-F', but much faster.  It identifies each type of
2963 special file in the listing with a special character:
2964 .PP
2965 .RS +8
2966 .PD 0
2967 .TP 4
2968 /
2969 Directory
2970 .TP 4
2971 *
2972 Executable
2973 .TP 4
2974 #
2975 Block device
2976 .TP 4
2977 %
2978 Character device
2979 .TP 4
2980 |
2981 Named pipe (systems with named pipes only)
2982 .TP 4
2983 =
2984 Socket (systems with sockets only)
2985 .TP 4
2986 @
2987 Symbolic link (systems with symbolic links only)
2988 .TP 4
2989 +
2990 Hidden directory (AIX only) or context dependent (HP/UX only)
2991 .TP 4
2992 :
2993 Network special (HP/UX only)
2994 .PD
2995 .PP
2996 If the \fBlistlinks\fR shell variable is set, symbolic links are identified
2997 in more detail (on only systems that have them, of course):
2998 .PP
2999 .PD 0
3000 .TP 4
3001 @
3002 Symbolic link to a non-directory
3003 .TP 4
3004 >
3005 Symbolic link to a directory
3006 .TP 4
3007 &
3008 Symbolic link to nowhere
3009 .PD
3010 .PP
3011 \fBlistlinks\fR also slows down \fIls\-F\fR and causes partitions holding
3012 files pointed to by symbolic links to be mounted.
3013 .PP
3014 If the \fBlistflags\fR shell variable is set to `x', `a' or `A', or any
3015 combination thereof (e.g., `xA'), they are used as flags to \fIls\-F\fR,
3016 making it act like `ls \-xF', `ls \-Fa', `ls \-FA' or a combination
3017 (e.g., `ls \-FxA').
3018 On machines where `ls \-C' is not the default, \fIls\-F\fR acts like `ls \-CF',
3019 unless \fBlistflags\fR contains an `x', in which case it acts like `ls \-xF'.
3020 \fIls\-F\fR passes its arguments to \fIls\fR(1) if it is given any switches,
3021 so `alias ls ls\-F' generally does the right thing.
3022 .PP
3023 The \fBls\-F\fR builtin can list files using different colors depending on the
3024 filetype or extension.  See the \fBcolor\fR \fItcsh\fR variable and the
3025 \fBLS_COLORS\fR environment variable.
3026 .RE
3027 .PP
3028 .B migrate \fR[\fB\-\fIsite\fR] \fIpid\fR|\fB%\fIjobid\fR ... (+)
3029 .PD 0
3030 .TP 8
3031 .B migrate \-\fIsite\fR (+)
3032 The first form migrates the process or job to the site specified or the
3033 default site determined by the system path.
3034 The second form is equivalent to `migrate \-\fIsite\fR $$': it migrates the
3035 current process to the specified site.  Migrating the shell
3036 itself can cause unexpected behavior, because the shell
3037 does not like to lose its tty.  (TCF only)
3038 .PD
3039 .TP 8
3040 .B newgrp \fR[\fB\-\fR] \fIgroup\fR (+)
3041 Equivalent to `exec newgrp'; see \fInewgrp\fR(1).
3042 Available only if the shell was so compiled;
3043 see the \fBversion\fR shell variable.
3044 .TP 8
3045 .B nice \fR[\fB+\fInumber\fR] [\fIcommand\fR]
3046 Sets the scheduling priority for the shell to \fInumber\fR, or, without
3047 \fInumber\fR, to 4.  With \fIcommand\fR, runs \fIcommand\fR at the appropriate
3048 priority.
3049 The greater the \fInumber\fR, the less cpu
3050 the process gets.  The super-user may specify negative
3051 priority by using `nice \-number ...'.  Command is always
3052 executed in a sub-shell, and the restrictions placed on
3053 commands in simple \fIif\fR statements apply.
3054 .TP 8
3055 .B nohup \fR[\fIcommand\fR]
3056 With \fIcommand\fR, runs \fIcommand\fR such that it will ignore hangup signals.
3057 Note that commands may set their own response to hangups, overriding \fInohup\fR.
3058 Without an argument (allowed in only a shell script), causes the shell to
3059 ignore hangups for the remainder of the script.
3060 See also \fBSignal handling\fR and the \fIhup\fR builtin command.
3061 .TP 8
3062 .B notify \fR[\fB%\fIjob\fR ...]
3063 Causes the shell to notify the user asynchronously when the status of any
3064 of the specified jobs (or, without %\fIjob\fR, the current job) changes,
3065 instead of waiting until the next prompt as is usual.
3066 \fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
3067 under \fBJobs\fR.
3068 See also the \fBnotify\fR shell variable.
3069 .TP 8
3070 .B onintr \fR[\fB\-\fR|\fIlabel\fR]
3071 Controls the action of the shell on interrupts.  Without arguments,
3072 restores the default action of the shell on interrupts,
3073 which is to terminate shell scripts or to return to the
3074 terminal command input level.
3075 With `\-', causes all interrupts to be ignored.
3076 With \fIlabel\fR, causes the shell to execute a `goto \fIlabel\fR'
3077 when an interrupt is received or a child process terminates because it was
3078 interrupted.
3079 .IP "" 8
3080 \fIonintr\fR is ignored if the shell is running detached and in system
3081 startup files (see \fBFILES\fR), where interrupts are disabled anyway.
3082 .TP 8
3083 .B popd \fR[\fB\-p\fR] [\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR] \fR[\fB+\fIn\fR]
3084 Without arguments, pops the directory stack and returns to the new top directory.
3085 With a number `+\fIn\fR', discards the \fIn\fR'th entry in the stack.
3086 .IP "" 8
3087 Finally, all forms of \fIpopd\fR print the final directory stack,
3088 just like \fIdirs\fR.  The \fBpushdsilent\fR shell variable can be set to
3089 prevent this and the \fB\-p\fR flag can be given to override \fBpushdsilent\fR.
3090 The \fB\-l\fR, \fB\-n\fR and \fB\-v\fR flags have the same effect on \fIpopd\fR
3091 as on \fIdirs\fR.  (+)
3092 .TP 8
3093 .B printenv \fR[\fIname\fR] (+)
3094 Prints the names and values of all environment variables or,
3095 with \fIname\fR, the value of the environment variable \fIname\fR.
3096 .TP 8
3097 .B pushd \fR[\fB\-p\fR] [\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR] [\fIname\fR|\fB+\fIn\fR]
3098 Without arguments, exchanges the top two elements of the directory stack.
3099 If \fBpushdtohome\fR is set, \fIpushd\fR without arguments does `pushd ~',
3100 like \fIcd\fR.  (+)
3101 With \fIname\fR, pushes the current working directory onto the directory
3102 stack and changes to \fIname\fR.
3103 If \fIname\fR is `\-' it is interpreted as the previous working directory
3104 (see \fBFilename substitution\fR).  (+)
3105 If \fBdunique\fR is set, \fIpushd\fR removes any instances of \fIname\fR
3106 from the stack before pushing it onto the stack.  (+)
3107 With a number `+\fIn\fR', rotates the \fIn\fRth element of the
3108 directory stack around to be the top element and changes to it.
3109 If \fBdextract\fR is set, however, `pushd +\fIn\fR' extracts the \fIn\fRth
3110 directory, pushes it onto the top of the stack and changes to it.  (+)
3111 .IP "" 8
3112 Finally, all forms of \fIpushd\fR print the final directory stack,
3113 just like \fIdirs\fR.  The \fBpushdsilent\fR shell variable can be set to
3114 prevent this and the \fB\-p\fR flag can be given to override \fBpushdsilent\fR.
3115 The \fB\-l\fR, \fB\-n\fR and \fB\-v\fR flags have the same effect on \fIpushd\fR
3116 as on \fIdirs\fR.  (+)
3117 .TP 8
3118 .B rehash
3119 Causes the internal hash table of the contents of the
3120 directories in the \fBpath\fR variable to be recomputed.  This is
3121 needed if new commands are added to directories in \fBpath\fR
3122 while you are logged in.  This should be necessary only if
3123 you add commands to one of your own directories, or if a
3124 systems programmer changes the contents of one of the
3125 system directories.  Also flushes the cache of home directories
3126 built by tilde expansion.
3127 .TP 8
3128 .B repeat \fIcount command
3129 The specified \fIcommand\fR,
3130 which is subject to the same restrictions as the \fIcommand\fR
3131 in the one line \fIif\fR statement above, is executed \fIcount\fR times.
3132 I/O redirections occur exactly once, even if \fIcount\fR is 0.
3133 .TP 8
3134 .B rootnode //\fInodename \fR(+)
3135 Changes the rootnode to //\fInodename\fR, so that `/' will be interpreted
3136 as `//\fInodename\fR'.  (Domain/OS only)
3137 .PP
3138 .B sched \fR(+)
3139 .br
3140 .B sched \fR[\fB+\fR]\fIhh:mm command\fR \fR(+)
3141 .PD 0
3142 .TP 8
3143 .B sched \-\fIn\fR (+)
3144 The first form prints the scheduled-event list.
3145 The \fBsched\fR shell variable may be set to define the format in which
3146 the scheduled-event list is printed.
3147 The second form adds \fIcommand\fR to the scheduled-event list.
3148 For example,
3149 .PD
3150 .RS +8
3151 .IP "" 4
3152 > sched 11:00 echo It\\'s eleven o\\'clock.
3153 .PP
3154 causes the shell to echo `It's eleven o'clock.' at 11 AM.
3155 The time may be in 12-hour AM/PM format
3156 .IP "" 4
3157 > sched 5pm set prompt='[%h] It\\'s after 5; go home: >'
3158 .PP
3159 or may be relative to the current time:
3160 .IP "" 4
3161 > sched +2:15 /usr/lib/uucp/uucico \-r1 \-sother
3162 .PP
3163 A relative time specification may not use AM/PM format.
3164 The third form removes item \fIn\fR from the event list:
3165 .IP "" 4
3166 > sched
3167 .br
3168      1  Wed Apr  4 15:42  /usr/lib/uucp/uucico \-r1 \-sother
3169 .br
3170      2  Wed Apr  4 17:00  set prompt=[%h] It's after 5; go home: >
3171 .br
3172 > sched \-2
3173 .br
3174 > sched
3175 .br
3176      1  Wed Apr  4 15:42  /usr/lib/uucp/uucico \-r1 \-sother
3177 .PP
3178 A command in the scheduled-event list is executed just before the first
3179 prompt is printed after the time when the command is scheduled.
3180 It is possible to miss the exact time when the command is to be run, but
3181 an overdue command will execute at the next prompt.
3182 A command which comes due while the shell
3183 is waiting for user input is executed immediately.
3184 However, normal operation of an already-running command will not
3185 be interrupted so that a scheduled-event list element may be run.
3186 .PP
3187 This mechanism is similar to, but not the same as, the \fIat\fR(1)
3188 command on some Unix systems.
3189 Its major disadvantage is that it may not run a command at exactly the
3190 specified time.
3191 Its major advantage is that because \fIsched\fR runs directly from
3192 the shell, it has access to shell variables and other structures.
3193 This provides a mechanism for changing one's working environment
3194 based on the time of day.
3195 .RE
3196 .PP
3197 .B set
3198 .br
3199 .B set \fIname\fR ...
3200 .br
3201 .B set \fIname\fR\fB=\fIword\fR ...
3202 .br
3203 .B set [\-r] [\-f|\-l] \fIname\fR\fB=(\fIwordlist\fB)\fR ... (+)
3204 .br
3205 .B set \fIname[index]\fR\fB=\fIword\fR ...
3206 .br
3207 .B set \-r \fR(+)
3208 .br
3209 .B set \-r \fIname\fR ... (+)
3210 .PD 0
3211 .TP 8
3212 .B set \-r \fIname\fR\fB=\fIword\fR ... (+)
3213 The first form of the command prints the value of all shell variables.
3214 Variables which contain more than a single word print as a
3215 parenthesized word list.
3216 The second form sets \fIname\fR to the null string.
3217 The third form sets \fIname\fR to the single \fIword\fR.
3218 The fourth form sets \fIname\fR to the list of words in
3219 \fIwordlist\fR.  In all cases the value is command and filename expanded.
3220 If \-r is specified, the value is set read-only.  If \-f or \-l are
3221 specified, set only unique words keeping their order.
3222 \-f prefers the first occurrence of a word, and \-l the last.
3223 The fifth form sets the \fIindex\fR'th component of name to \fIword\fR;
3224 this component must already exist.
3225 The sixth form lists only the names of all shell variables that are read-only.
3226 The seventh form makes \fIname\fR read-only, whether or not it has a value.
3227 The second form sets \fIname\fR to the null string.
3228 The eighth form is the same as the third form, but
3229 make \fIname\fR read-only at the same time.
3230 .PD
3231 .IP "" 8
3232 These arguments can be repeated to set and/or make read-only multiple variables
3233 in a single set command.  Note, however, that variable expansion
3234 happens for all arguments before any setting occurs.  Note also that `=' can
3235 be adjacent to both \fIname\fR and \fIword\fR or separated from both by
3236 whitespace, but cannot be adjacent to only one or the other.
3237 See also the \fIunset\fR builtin command.
3238 .TP 8
3239 .B setenv \fR[\fIname \fR[\fIvalue\fR]]
3240 Without arguments, prints the names and values of all environment variables.
3241 Given \fIname\fR, sets the environment variable \fIname\fR to \fIvalue\fR
3242 or, without \fIvalue\fR, to the null string.
3243 .TP 8
3244 .B setpath \fIpath \fR(+)
3245 Equivalent to \fIsetpath\fR(1).  (Mach only)
3246 .TP 8
3247 .B setspath\fR LOCAL|\fIsite\fR|\fIcpu\fR ...  (+)
3248 Sets the system execution path.  (TCF only)
3249 .TP 8
3250 .B settc \fIcap value \fR(+)
3251 Tells the shell to believe that the terminal capability \fIcap\fR
3252 (as defined in \fItermcap\fR(5)) has the value \fIvalue\fR.
3253 No sanity checking is done.
3254 Concept terminal users may have to `settc xn no' to get proper
3255 wrapping at the rightmost column.
3256 .TP 8
3257 .B setty \fR[\fB\-d\fR|\fB\-q\fR|\fB\-x\fR] [\fB\-a\fR] [[\fB+\fR|\fB\-\fR]\fImode\fR] (+)
3258 Controls which tty modes (see \fBTerminal management\fR)
3259 the shell does not allow to change.
3260 \fB\-d\fR, \fB\-q\fR or \fB\-x\fR tells \fIsetty\fR to act
3261 on the `edit', `quote' or `execute' set of tty modes respectively; without
3262 \fB\-d\fR, \fB\-q\fR or \fB\-x\fR, `execute' is used.
3263 .IP "" 8
3264 Without other arguments, \fIsetty\fR lists the modes in the chosen set
3265 which are fixed on (`+mode') or off (`\-mode').
3266 The available modes, and thus the display, vary from system to system.
3267 With \fB\-a\fR, lists all tty modes in the chosen set
3268 whether or not they are fixed.
3269 With \fB+\fImode\fR, \fB\-\fImode\fR or \fImode\fR, fixes \fImode\fR on or off
3270 or removes control from \fImode\fR in the chosen set.
3271 For example, `setty +echok echoe' fixes `echok' mode on and allows commands
3272 to turn `echoe' mode on or off, both when the shell is executing commands.
3273 .TP 8
3274 .B setxvers\fR [\fIstring\fR] (+)
3275 Set the experimental version prefix to \fIstring\fR, or removes it
3276 if \fIstring\fR is omitted.  (TCF only)
3277 .TP 8
3278 .B shift \fR[\fIvariable\fR]
3279 Without arguments, discards \fBargv\fR[1] and shifts the members of
3280 \fBargv\fR to the left.  It is an error for \fBargv\fR not to be set or to have
3281 less than one word as value.  With \fIvariable\fR, performs the
3282 same function on \fIvariable\fR.
3283 .TP 8
3284 .B source \fR[\fB\-h\fR] \fIname\fR [\fIargs\fR ...]
3285 The shell reads and executes commands from \fIname\fR.
3286 The commands are not placed on the history list.
3287 If any \fIargs\fR are given, they are placed in \fBargv\fR.  (+)
3288 \fIsource\fR commands may be nested;
3289 if they are nested too deeply the shell may run out of file descriptors.
3290 An error in a \fIsource\fR at any level terminates all nested
3291 \fIsource\fR commands.
3292 With \fB\-h\fR, commands are placed on the history list instead of being
3293 executed, much like `history \-L'.
3294 .TP 8
3295 .B stop \fB%\fIjob\fR|\fIpid\fR ...
3296 Stops the specified jobs or processes which are executing in the background.
3297 \fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
3298 under \fBJobs\fR.
3299 There is no default \fIjob\fR; saying just `stop' does not stop
3300 the current job.
3301 .TP 8
3302 .B suspend
3303 Causes the shell to stop in its tracks, much as if it had
3304 been sent a stop signal with \fB^Z\fR.  This is most often used to
3305 stop shells started by \fIsu\fR(1).
3306 .PP
3307 .B switch (\fIstring\fB)
3308 .br
3309 .B case \fIstr1\fB:
3310 .PD 0
3311 .IP "" 4
3312 \&...
3313 .br
3314 .B breaksw
3315 .PP
3316 \&...
3317 .PP
3318 .B default:
3319 .IP "" 4
3320 \&...
3321 .br
3322 .B breaksw
3323 .TP 8
3324 .B endsw
3325 Each case label is successively matched, against the
3326 specified \fIstring\fR which is first command and filename expanded.
3327 The file metacharacters `*', `?' and `[...]'  may be used
3328 in the case labels, which are variable expanded.  If none
3329 of the labels match before a `default' label is found, then
3330 the execution begins after the default label.  Each case
3331 label and the default label must appear at the beginning of
3332 a line.  The command \fIbreaksw\fR causes execution to continue
3333 after the \fIendsw\fR.  Otherwise control may fall through case
3334 labels and default labels as in C.  If no label matches and
3335 there is no default, execution continues after the \fIendsw\fR.
3336 .PD
3337 .TP 8
3338 .B telltc \fR(+)
3339 Lists the values of all terminal capabilities (see \fItermcap\fR(5)).
3340 .TP 8
3341 .B termname \fR[\fIterminal type\fR] \fR(+)
3342 Tests if \fIterminal type\fR (or the current value of \fBTERM\fR if no
3343 \fIterminal type\fR is given) has an entry in the hosts termcap(5) or
3344 terminfo(5) database. Prints the terminal type to stdout and returns 0
3345 if an entry is present otherwise returns 1.
3346 .TP 8
3347 .B time \fR[\fIcommand\fR]
3348 Executes \fIcommand\fR (which must be a simple command, not an alias,
3349 a pipeline, a command list or a parenthesized command list)
3350 and prints a time summary as described under the \fBtime\fR variable.
3351 If necessary, an extra shell is created to print the time statistic when
3352 the command completes.
3353 Without \fIcommand\fR, prints a time summary for the current shell and its
3354 children.
3355 .TP 8
3356 .B umask \fR[\fIvalue\fR]
3357 Sets the file creation mask to \fIvalue\fR, which is given in octal.
3358 Common values for the mask are
3359 002, giving all access to the group and read and execute access to others, and
3360 022, giving read and execute access to the group and others.
3361 Without \fIvalue\fR, prints the current file creation mask.
3362 .TP 8
3363 .B unalias \fIpattern
3364 .br
3365 Removes all aliases whose names match \fIpattern\fR.
3366 `unalias *' thus removes all aliases.
3367 It is not an error for nothing to be \fIunalias\fRed.
3368 .TP 8
3369 .B uncomplete \fIpattern\fR (+)
3370 Removes all completions whose names match \fIpattern\fR.
3371 `uncomplete *' thus removes all completions.
3372 It is not an error for nothing to be \fIuncomplete\fRd.
3373 .TP 8
3374 .B unhash
3375 Disables use of the internal hash table to speed location of
3376 executed programs.
3377 .TP 8
3378 .B universe \fIuniverse\fR (+)
3379 Sets the universe to \fIuniverse\fR.  (Masscomp/RTU only)
3380 .TP 8
3381 .B unlimit \fR[\fB\-hf\fR] [\fIresource\fR]
3382 Removes the limitation on \fIresource\fR or, if no \fIresource\fR is
3383 specified, all \fIresource\fR limitations.
3384 With \fB\-h\fR, the corresponding hard limits are removed.
3385 Only the super-user may do this.
3386 Note that \fBunlimit\fR may not exit successful, since most systems
3387 do not allow \fIdescriptors\fR to be unlimited.
3388 With \fB\-f\fR errors are ignored.
3389 .TP 8
3390 .B unset \fIpattern
3391 Removes all variables whose names match \fIpattern\fR, unless they are read-only.
3392 `unset *' thus removes all variables unless they are read-only;
3393 this is a bad idea.
3394 It is not an error for nothing to be \fIunset\fR.
3395 .TP 8
3396 .B unsetenv \fIpattern
3397 Removes all environment variables whose names match \fIpattern\fR.
3398 `unsetenv *' thus removes all environment variables;
3399 this is a bad idea.
3400 It is not an error for nothing to be \fIunsetenv\fRed.
3401 .TP 8
3402 .B ver \fR[\fIsystype\fR [\fIcommand\fR]] (+)
3403 Without arguments, prints \fBSYSTYPE\fR.  With \fIsystype\fR, sets \fBSYSTYPE\fR
3404 to \fIsystype\fR.  With \fIsystype\fR and \fIcommand\fR, executes \fIcommand\fR
3405 under \fIsystype\fR.  \fIsystype\fR may be `bsd4.3' or `sys5.3'.
3406 (Domain/OS only)
3407 .TP 8
3408 .B wait
3409 The shell waits for all background jobs.  If the shell is interactive, an
3410 interrupt will disrupt the wait and cause the shell to print the names and job
3411 numbers of all outstanding jobs.
3412 .TP 8
3413 .B warp \fIuniverse\fR (+)
3414 Sets the universe to \fIuniverse\fR.  (Convex/OS only)
3415 .TP 8
3416 .B watchlog \fR(+)
3417 An alternate name for the \fIlog\fR builtin command (q.v.).
3418 Available only if the shell was so compiled;
3419 see the \fBversion\fR shell variable.
3420 .TP 8
3421 .B where \fIcommand\fR (+)
3422 Reports all known instances of \fIcommand\fR, including aliases, builtins and
3423 executables in \fBpath\fR.
3424 .TP 8
3425 .B which\fR \fIcommand\fR (+)
3426 Displays the command that will be executed by the shell after substitutions,
3427 \fBpath\fR searching, etc.
3428 The builtin command is just like \fIwhich\fR(1), but it correctly reports
3429 \fItcsh\fR aliases and builtins and is 10 to 100 times faster.
3430 See also the \fIwhich-command\fR editor command.
3431 .PP
3432 .B while (\fIexpr\fB)\fR
3433 .br
3434 \&...
3435 .PD 0
3436 .TP 8
3437 .B end
3438 Executes the commands between the \fIwhile\fR and the matching \fIend\fR
3439 while \fIexpr\fR (an expression, as described under \fBExpressions\fR)
3440 evaluates non-zero.
3441 \fIwhile\fR and \fIend\fR must appear alone on their input lines.
3442 \fIbreak\fR and \fIcontinue\fR may be used to terminate or continue the
3443 loop prematurely.
3444 If the input is a terminal, the user is prompted the first time
3445 through the loop as with \fIforeach\fR.
3446 .PD
3447 .SS "Special aliases (+)"
3448 If set, each of these aliases executes automatically at the indicated time.
3449 They are all initially undefined.
3450 .TP 8
3451 .B beepcmd
3452 Runs when the shell wants to ring the terminal bell.
3453 .TP 8
3454 .B cwdcmd
3455 Runs after every change of working directory.  For example, if the user is
3456 working on an X window system using \fIxterm\fR(1) and a re-parenting window
3457 manager that supports title bars such as \fItwm\fR(1) and does
3458 .RS +8
3459 .IP "" 4
3460 > alias cwdcmd  'echo \-n "^[]2;${HOST}:$cwd ^G"'
3461 .PP
3462 then the shell will change the title of the running \fIxterm\fR(1)
3463 to be the name of the host, a colon, and the full current working directory.
3464 A fancier way to do that is
3465 .IP "" 4
3466 > alias cwdcmd 'echo \-n "^[]2;${HOST}:$cwd^G^[]1;${HOST}^G"'
3467 .PP
3468 This will put the hostname and working directory on the title bar but
3469 only the hostname in the icon manager menu.
3470 .PP
3471 Note that putting a \fIcd\fR, \fIpushd\fR or \fIpopd\fR in \fIcwdcmd\fR
3472 may cause an infinite loop.  It is the author's opinion that anyone doing
3473 so will get what they deserve.
3474 .RE
3475 .TP 8
3476 .B jobcmd
3477 Runs before each command gets executed, or when the command changes state.
3478 This is similar to \fIpostcmd\fR, but it does not print builtins.
3479 .RS +8
3480 .IP "" 4
3481 > alias jobcmd  'echo \-n "^[]2\e;\e!#:q^G"'
3482 .PP
3483 then executing \fIvi foo.c\fR will put the command string in the xterm title bar.
3484 .RE
3485 .TP 8
3486 .B helpcommand
3487 Invoked by the \fBrun-help\fR editor command.  The command name for which help
3488 is sought is passed as sole argument.
3489 For example, if one does
3490 .RS +8
3491 .IP "" 4
3492 > alias helpcommand '\e!:1 --help'
3493 .PP
3494 then the help display of the command itself will be invoked, using the GNU
3495 help calling convention.
3496 Currently there is no easy way to account for various calling conventions (e.g.,
3497 the customary Unix `-h'), except by using a table of many commands.
3498 .RE
3499 .TP 8
3500 .B periodic
3501 Runs every \fBtperiod\fR minutes.  This provides a convenient means for
3502 checking on common but infrequent changes such as new mail.  For example,
3503 if one does
3504 .RS +8
3505 .IP "" 4
3506 > set tperiod = 30
3507 .br
3508 > alias periodic checknews
3509 .PP
3510 then the \fIchecknews\fR(1) program runs every 30 minutes.
3511 If \fIperiodic\fR is set but \fBtperiod\fR is unset or set to 0,
3512 \fIperiodic\fR behaves like \fIprecmd\fR.
3513 .RE
3514 .TP 8
3515 .B precmd
3516 Runs just before each prompt is printed.  For example, if one does
3517 .RS +8
3518 .IP "" 4
3519 > alias precmd date
3520 .PP
3521 then \fIdate\fR(1) runs just before the shell prompts for each command.
3522 There are no limits on what \fIprecmd\fR can be set to do, but discretion
3523 should be used.
3524 .RE
3525 .TP 8
3526 .B postcmd
3527 Runs before each command gets executed.
3528 .RS +8
3529 .IP "" 4
3530 > alias postcmd  'echo \-n "^[]2\e;\e!#:q^G"'
3531 .PP
3532 then executing \fIvi foo.c\fR will put the command string in the xterm title bar.
3533 .RE
3534 .TP 8
3535 .B shell
3536 Specifies the interpreter for executable scripts which do not themselves
3537 specify an interpreter.  The first word should be a full path name to the
3538 desired interpreter (e.g., `/bin/csh' or `/usr/local/bin/tcsh').
3539 .SS "Special shell variables"
3540 The variables described in this section have special meaning to the shell.
3541 .PP
3542 The shell sets \fBaddsuffix\fR, \fBargv\fR, \fBautologout\fR, \fBcsubstnonl\fR, \fBcommand\fR, \fBecho_style\fR,
3543 \fBedit\fR, \fBgid\fR, \fBgroup\fR, \fBhome\fR, \fBloginsh\fR, \fBoid\fR, \fBpath\fR,
3544 \fBprompt\fR, \fBprompt2\fR, \fBprompt3\fR, \fBshell\fR, \fBshlvl\fR,
3545 \fBtcsh\fR, \fBterm\fR, \fBtty\fR, \fBuid\fR, \fBuser\fR and \fBversion\fR at
3546 startup; they do not change thereafter unless changed by the user.  The shell
3547 updates \fBcwd\fR, \fBdirstack\fR, \fBowd\fR and \fBstatus\fR when necessary,
3548 and sets \fBlogout\fR on logout.
3549 .PP
3550 The shell synchronizes \fBgroup\fR, \fBhome\fR, \fBpath\fR, \fBshlvl\fR,
3551 \fBterm\fR and \fBuser\fR with the environment variables of the same names:
3552 whenever the environment variable changes the shell changes the corresponding
3553 shell variable to match (unless the shell variable is read-only) and vice
3554 versa.  Note that although \fBcwd\fR and \fBPWD\fR have identical meanings, they
3555 are not synchronized in this manner, and that the shell automatically
3556 interconverts the different formats of \fBpath\fR and \fBPATH\fR.
3557 .TP 8
3558 .B addsuffix \fR(+)
3559 If set, filename completion adds `/' to the end of directories and a space
3560 to the end of normal files when they are matched exactly.
3561 Set by default.
3562 .TP 8
3563 .B afsuser \fR(+)
3564 If set, \fBautologout\fR's autolock feature uses its value instead of
3565 the local username for kerberos authentication.
3566 .TP 8
3567 .B ampm \fR(+)
3568 If set, all times are shown in 12-hour AM/PM format.
3569 .TP 8
3570 .B argv
3571 The arguments to the shell.  Positional parameters are taken from \fBargv\fR,
3572 i.e., `$1' is replaced by `$argv[1]', etc.
3573 Set by default, but usually empty in interactive shells.
3574 .TP 8
3575 .B autocorrect \fR(+)
3576 If set, the \fIspell-word\fR editor command is invoked automatically before
3577 each completion attempt.
3578 .TP 8
3579 .B autoexpand \fR(+)
3580 If set, the \fIexpand-history\fR editor command is invoked automatically
3581 before each completion attempt. If this is set to \fIonlyhistory\fR, then
3582 only history will be expanded and a second completion will expand filenames.
3583 .TP 8
3584 .B autolist \fR(+)
3585 If set, possibilities are listed after an ambiguous completion.
3586 If set to `ambiguous', possibilities are listed only when no new
3587 characters are added by completion.
3588 .TP 8
3589 .B autologout \fR(+)
3590 The first word is the number of minutes of inactivity before automatic
3591 logout.  The optional second word is the number of minutes of inactivity
3592 before automatic locking.
3593 When the shell automatically logs out,
3594 it prints `auto-logout', sets the variable logout to `automatic' and exits.
3595 When the shell automatically locks, the user is required to enter his password
3596 to continue working.  Five incorrect attempts result in automatic logout.
3597 Set to `60' (automatic logout after 60 minutes, and no locking) by default
3598 in login and superuser shells, but not if the shell thinks it is running
3599 under a window system (i.e., the \fBDISPLAY\fR environment variable is set),
3600 the tty is a pseudo-tty (pty) or the shell was not so compiled (see the
3601 \fBversion\fR shell variable).
3602 See also the \fBafsuser\fR and \fBlogout\fR shell variables.
3603 .TP 8
3604 .B backslash_quote \fR(+)
3605 If set, backslashes (`\\') always quote `\\', `'', and `"'.  This may make
3606 complex quoting tasks easier, but it can cause syntax errors in \fIcsh\fR(1)
3607 scripts.
3608 .TP 8
3609 .B catalog
3610 The file name of the message catalog.
3611 If set, tcsh use `tcsh.${catalog}' as a message catalog instead of
3612 default `tcsh'.
3613 .TP 8
3614 .B cdpath
3615 A list of directories in which \fIcd\fR should search for
3616 subdirectories if they aren't found in the current directory.
3617 .TP 8
3618 .B color
3619 If set, it enables color display for the builtin \fBls\-F\fR and it passes
3620 \fB\-\-color=auto\fR to \fBls\fR.  Alternatively, it can be set to only
3621 \fBls\-F\fR or only \fBls\fR to enable color to only one command.  Setting
3622 it to nothing is equivalent to setting it to \fB(ls\-F ls)\fR.
3623 .TP 8
3624 .B colorcat
3625 If set, it enables color escape sequence for NLS message files.
3626 And display colorful NLS messages.
3627 .TP 8
3628 .B command \fR(+)
3629 If set, the command which was passed to the shell with the \fB-c\fR flag (q.v.).
3630 .TP 8
3631 .B compat_expr \fR(+)
3632 If set, the shell will evaluate expressions right to left, like the original
3633 \fIcsh\fR.
3634 .TP 8
3635 .B complete \fR(+)
3636 If set to `enhance', completion 1) ignores case and 2) considers
3637 periods, hyphens and underscores (`.', `\-' and `_') to be word
3638 separators and hyphens and underscores to be equivalent. If set to
3639 `igncase', the completion becomes case insensitive.
3640 .TP 8
3641 .B continue \fR(+)
3642 If set to a list of commands, the shell will continue the listed
3643 commands, instead of starting a new one.
3644 .TP 8
3645 .B continue_args \fR(+)
3646 Same as continue, but the shell will execute:
3647 .RS +8
3648 .IP "" 4
3649 echo `pwd` $argv > ~/.<cmd>_pause; %<cmd>
3650 .RE
3651 .TP 8
3652 .B correct \fR(+)
3653 If set to `cmd', commands are automatically spelling-corrected.
3654 If set to `complete', commands are automatically completed.
3655 If set to `all', the entire command line is corrected.
3656 .TP 8
3657 .B csubstnonl \fR(+)
3658 If set, newlines and carriage returns in command substitution are
3659 replaced by spaces.  Set by default.
3660 .TP 8
3661 .B cwd
3662 The full pathname of the current directory.
3663 See also the \fBdirstack\fR and \fBowd\fR shell variables.
3664 .TP 8
3665 .B dextract \fR(+)
3666 If set, `pushd +\fIn\fR' extracts the \fIn\fRth directory from the directory
3667 stack rather than rotating it to the top.
3668 .TP 8
3669 .B dirsfile \fR(+)
3670 The default location in which `dirs \-S' and `dirs \-L' look for
3671 a history file.  If unset, \fI~/.cshdirs\fR is used.
3672 Because only \fI~/.tcshrc\fR is normally sourced before \fI~/.cshdirs\fR,
3673 \fBdirsfile\fR should be set in \fI~/.tcshrc\fR rather than \fI~/.login\fR.
3674 .TP 8
3675 .B dirstack \fR(+)
3676 An array of all the directories on the directory stack.
3677 `$dirstack[1]' is the current working directory, `$dirstack[2]'
3678 the first directory on the stack, etc.
3679 Note that the current working directory is `$dirstack[1]' but `=0' in
3680 directory stack substitutions, etc.
3681 One can change the stack arbitrarily by setting \fBdirstack\fR,
3682 but the first element (the current working directory) is always correct.
3683 See also the \fBcwd\fR and \fBowd\fR shell variables.
3684 .TP 8
3685 .B dspmbyte \fR(+)
3686 Has an affect iff 'dspm' is listed as part of the \fBversion\fR shell variable.
3687 If set to `euc', it enables display and editing EUC-kanji(Japanese) code.
3688 If set to `sjis', it enables display and editing Shift-JIS(Japanese) code.
3689 If set to `big5', it enables display and editing Big5(Chinese) code.
3690 If set to `utf8', it enables display and editing Utf8(Unicode) code.
3691 If set to the following format, it enables display and editing of original
3692 multi-byte code format:
3693 .RS +8
3694 .IP "" 4
3695 > set dspmbyte = 0000....(256 bytes)....0000
3696 .PP
3697 The table requires \fBjust\fR 256 bytes.  Each character of 256 characters
3698 corresponds (from left to right) to the ASCII codes 0x00, 0x01, ... 0xff.  Each
3699 character
3700 .\" (position in this table?)
3701 is set to number 0,1,2 and 3.  Each number has the following meaning:
3702 .br
3703   0 ... not used for multi-byte characters.
3704 .br
3705   1 ... used for the first byte of a multi-byte character.
3706 .br
3707   2 ... used for the second byte of a multi-byte character.
3708 .br
3709   3 ... used for both the first byte and second byte of a multi-byte character.
3710 .\" SHK: I tried my best to get the following to be grammatically correct.
3711 .\" However, I still don't understand what's going on here.  In the
3712  \" following example, there are three bytes, but the text seems to refer to
3713  \" each nybble as a character.  What's going on here?  It this 3-byte code
3714  \" in the table?  The text above seems to imply that there are 256
3715  \" characters/bytes in the table.  If I get some more info on this (perhaps
3716  \" a complete example), I could fix the text to be grammatically correct.
3717  \" (steve.kelem@xilinx.com 1999/09/13)
3718 .PP
3719   Example:
3720 .br
3721 If set to `001322', the first character (means 0x00 of the ASCII code) and
3722 second character (means 0x01 of ASCII code) are set to `0'.  Then, it is not
3723 used for multi-byte characters.  The 3rd character (0x02) is set to '1',
3724 indicating that it is used for the first byte of a multi-byte character.
3725 The 4th character(0x03) is set '3'.  It is used for both the first byte and
3726 the second byte of a multi-byte character.  The 5th and 6th characters
3727 (0x04,0x05) are set to '2', indicating that they are used for the second
3728 byte of a multi-byte character.
3729 .PP
3730 The GNU fileutils version of ls cannot display multi-byte
3731 filenames without the -N ( --literal ) option.   If you are using
3732 this version, set the second word of dspmbyte to "ls".  If not, for
3733 example, "ls-F -l" cannot display multi-byte filenames.
3734 .PP
3735   Note:
3736 .br
3737 This variable can only be used if KANJI and DSPMBYTE has been defined at
3738 compile time.
3739 .RE
3740 .TP 8
3741 .B dunique \fR(+)
3742 If set, \fIpushd\fR removes any instances of \fIname\fR
3743 from the stack before pushing it onto the stack.
3744 .TP 8
3745 .B echo
3746 If set, each command with its arguments is echoed just before it is
3747 executed.  For non-builtin commands all expansions occur before
3748 echoing.  Builtin commands are echoed before command and filename
3749 substitution, because these substitutions are then done selectively.
3750 Set by the \fB\-x\fR command line option.
3751 .TP 8
3752 .B echo_style \fR(+)
3753 The style of the \fIecho\fR builtin.  May be set to
3754 .PP
3755 .RS +8
3756 .PD 0
3757 .TP 8
3758 bsd
3759 Don't echo a newline if the first argument is `\-n'.
3760 .TP 8
3761 sysv
3762 Recognize backslashed escape sequences in echo strings.
3763 .TP 8
3764 both
3765 Recognize both the `\-n' flag and backslashed escape sequences; the default.
3766 .TP 8
3767 none
3768 Recognize neither.
3769 .PD
3770 .PP
3771 Set by default to the local system default.  The BSD and System V
3772 options are described in the \fIecho\fR(1) man pages on the appropriate
3773 systems.
3774 .RE
3775 .TP 8
3776 .B edit \fR(+)
3777 If set, the command-line editor is used.  Set by default in interactive
3778 shells.
3779 .TP 8
3780 .B ellipsis \fR(+)
3781 If set, the `%c'/`%.' and `%C' prompt sequences (see the \fBprompt\fR
3782 shell variable) indicate skipped directories with an ellipsis (`...')
3783 instead of `/<skipped>'.
3784 .TP 8
3785 .B fignore \fR(+)
3786 Lists file name suffixes to be ignored by completion.
3787 .TP 8
3788 .B filec
3789 In \fItcsh\fR, completion is always used and this variable is ignored
3790 by default. If 
3791 .B edit
3792 is unset, then the traditional \fIcsh\fR completion is used.
3793 If set in \fIcsh\fR, filename completion is used.
3794 .TP 8
3795 .B gid \fR(+)
3796 The user's real group ID.
3797 .TP 8
3798 .B group \fR(+)
3799 The user's group name.
3800 .TP 8
3801 .B highlight
3802 If set, the incremental search match (in \fIi-search-back\fR and
3803 \fIi-search-fwd\fR) and the region between the mark and the cursor are
3804 highlighted in reverse video.
3805
3806 Highlighting requires more frequent terminal writes, which introduces extra
3807 overhead. If you care about terminal performance, you may want to leave this
3808 unset.
3809 .TP 8
3810 .B histchars
3811 A string value determining the characters used in \fBHistory
3812 substitution\fR (q.v.).  The first character of its value is used as
3813 the history substitution character, replacing the default character
3814 `!'.  The second character of its value replaces the character `^' in
3815 quick substitutions.
3816 .TP 8
3817 .B histdup \fR(+)
3818 Controls handling of duplicate entries in the history list.  If set to
3819 `all' only unique history events are entered in the history list.  If
3820 set to `prev' and the last history event is the same as the current
3821 command, then the current command is not entered in the history.  If
3822 set to `erase' and the same event is found in the history list, that
3823 old event gets erased and the current one gets inserted.  Note that the
3824 `prev' and `all' options renumber history events so there are no gaps.
3825 .TP 8
3826 .B histfile \fR(+)
3827 The default location in which `history \-S' and `history \-L' look for
3828 a history file.  If unset, \fI~/.history\fR is used.  \fBhistfile\fR is
3829 useful when sharing the same home directory between different machines,
3830 or when saving separate histories on different terminals.  Because only
3831 \fI~/.tcshrc\fR is normally sourced before \fI~/.history\fR,
3832 \fBhistfile\fR should be set in \fI~/.tcshrc\fR rather than
3833 \fI~/.login\fR.
3834 .TP 8
3835 .B histlit \fR(+)
3836 If set, builtin and editor commands and the \fBsavehist\fR mechanism
3837 use the literal (unexpanded) form of lines in the history list.  See
3838 also the \fItoggle-literal-history\fR editor command.
3839 .TP 8
3840 .B history
3841 The first word indicates the number of history events to save.  The
3842 optional second word (+) indicates the format in which history is
3843 printed; if not given, `%h\\t%T\\t%R\\n' is used.  The format sequences
3844 are described below under \fBprompt\fR; note the variable meaning of
3845 `%R'.  Set to `100' by default.
3846 .TP 8
3847 .B home
3848 Initialized to the home directory of the invoker.  The filename
3849 expansion of `\fI~\fR' refers to this variable.
3850 .TP 8
3851 .B ignoreeof
3852 If set to the empty string or `0' and the input device is a terminal,
3853 the \fIend-of-file\fR command (usually generated by the user by typing
3854 `^D' on an empty line) causes the shell to print `Use "exit" to leave
3855 tcsh.' instead of exiting.  This prevents the shell from accidentally
3856 being killed.  Historically this setting exited after 26 successive
3857 EOF's to avoid infinite loops.  If set to a number \fIn\fR, the shell
3858 ignores \fIn - 1\fR consecutive \fIend-of-file\fRs and exits on the
3859 \fIn\fRth.  (+) If unset, `1' is used, i.e., the shell exits on a
3860 single `^D'.
3861 .TP 8
3862 .B implicitcd \fR(+)
3863 If set, the shell treats a directory name typed as a command as though
3864 it were a request to change to that directory.  If set to \fIverbose\fR,
3865 the change of directory is echoed to the standard output.  This behavior
3866 is inhibited in non-interactive shell scripts, or for command strings
3867 with more than one word.  Changing directory takes precedence over
3868 executing a like-named command, but it is done after alias
3869 substitutions.  Tilde and variable expansions work as expected.
3870 .TP 8
3871 .B inputmode \fR(+)
3872 If set to `insert' or `overwrite', puts the editor into that input mode
3873 at the beginning of each line.
3874 .TP 8
3875 .B killdup \fR(+)
3876 Controls handling of duplicate entries in the kill ring.  If set to
3877 `all' only unique strings are entered in the kill ring.  If set to
3878 `prev' and the last killed string is the same as the current killed
3879 string, then the current string is not entered in the ring.  If set
3880 to `erase' and the same string is found in the kill ring, the old
3881 string is erased and the current one is inserted.
3882 .TP 8
3883 .B killring \fR(+)
3884 Indicates the number of killed strings to keep in memory.  Set to `30'
3885 by default.  If unset or set to less than `2', the shell will only
3886 keep the most recently killed string.
3887 Strings are put in the killring by the editor commands that delete
3888 (kill) strings of text, e.g. \fIbackward-delete-word\fR,
3889 \fIkill-line\fR, etc, as well as the \fIcopy-region-as-kill\fR command.
3890 The \fIyank\fR editor command will yank the most recently killed string
3891 into the command-line, while \fIyank-pop\fR (see \fBEditor commands\fR)
3892 can be used to yank earlier killed strings.
3893 .TP 8
3894 .B listflags \fR(+)
3895 If set to `x', `a' or `A', or any combination thereof (e.g., `xA'), they
3896 are used as flags to \fIls\-F\fR, making it act like `ls \-xF', `ls
3897 \-Fa', `ls \-FA' or a combination (e.g., `ls \-FxA'): `a' shows all
3898 files (even if they start with a `.'), `A' shows all files but `.' and
3899 `..', and `x' sorts across instead of down.  If the second word of
3900 \fBlistflags\fR is set, it is used as the path to `ls(1)'.
3901 .TP 8
3902 .B listjobs \fR(+)
3903 If set, all jobs are listed when a job is suspended.  If set to `long',
3904 the listing is in long format.
3905 .TP 8
3906 .B listlinks \fR(+)
3907 If set, the \fIls\-F\fR builtin command shows the type of file to which
3908 each symbolic link points.
3909 .TP 8
3910 .B listmax \fR(+)
3911 The maximum number of items which the \fIlist-choices\fR editor command
3912 will list without asking first.
3913 .TP 8
3914 .B listmaxrows \fR(+)
3915 The maximum number of rows of items which the \fIlist-choices\fR editor
3916 command will list without asking first.
3917 .TP 8
3918 .B loginsh \fR(+)
3919 Set by the shell if it is a login shell.  Setting or unsetting it
3920 within a shell has no effect.  See also \fBshlvl\fR.
3921 .TP 8
3922 .B logout \fR(+)
3923 Set by the shell to `normal' before a normal logout, `automatic' before
3924 an automatic logout, and `hangup' if the shell was killed by a hangup
3925 signal (see \fBSignal handling\fR).  See also the \fBautologout\fR
3926 shell variable.
3927 .TP 8
3928 .B mail
3929 The names of the files or directories to check for incoming mail,
3930 separated by whitespace, and optionally preceded by a numeric word.
3931 Before each prompt, if 10 minutes have passed since the last check, the
3932 shell checks each file and says `You have new mail.' (or, if \fBmail\fR
3933 contains multiple files, `You have new mail in \fIname\fR.') if the
3934 filesize is greater than zero in size and has a modification time
3935 greater than its access time.
3936 .PP
3937 .RS +8
3938 .PD
3939 .PP
3940 If you are in a login shell, then no mail file is reported unless it has
3941 been modified after the time the shell has started up, to prevent
3942 redundant notifications.  Most login programs will tell you whether or not
3943 you have mail when you log in.
3944 .PP
3945 If a file specified in \fBmail\fR is a directory, the shell will count each
3946 file within that directory as a separate message, and will report `You have
3947 \fIn\fR mails.' or `You have \fIn\fR mails in \fIname\fR.' as appropriate.
3948 This functionality is provided primarily for those systems which store mail
3949 in this manner, such as the Andrew Mail System.
3950 .PP
3951 If the first word of \fBmail\fR is numeric it is taken as a different mail
3952 checking interval, in seconds.
3953 .PP
3954 Under very rare circumstances, the shell may report `You have mail.' instead
3955 of `You have new mail.'
3956 .RE
3957 .TP 8
3958 .B matchbeep \fR(+)
3959 If set to `never', completion never beeps.
3960 If set to `nomatch', it beeps only when there is no match.
3961 If set to `ambiguous', it beeps when there are multiple matches.
3962 If set to `notunique', it beeps when there is one exact and other longer matches.
3963 If unset, `ambiguous' is used.
3964 .TP 8
3965 .B nobeep \fR(+)
3966 If set, beeping is completely disabled.
3967 See also \fBvisiblebell\fR.
3968 .TP 8
3969 .B noclobber
3970 If set, restrictions are placed on output redirection to insure that files
3971 are not accidentally destroyed and that `>>' redirections refer to existing
3972 files, as described in the \fBInput/output\fR section.
3973 .TP 8
3974 .B noding
3975 If set, disable the printing of `DING!' in the \fBprompt\fR time
3976 specifiers at the change of hour.
3977 .TP 8
3978 .B noglob
3979 If set, \fBFilename substitution\fR and \fBDirectory stack substitution\fR
3980 (q.v.) are inhibited.  This is most useful in shell scripts which do not deal
3981 with filenames, or after a list of filenames has been obtained and further
3982 expansions are not desirable.
3983 .TP 8
3984 .B nokanji \fR(+)
3985 If set and the shell supports Kanji (see the \fBversion\fR shell variable),
3986 it is disabled so that the meta key can be used.
3987 .TP 8
3988 .B nonomatch
3989 If set, a \fBFilename substitution\fR or \fBDirectory stack substitution\fR
3990 (q.v.) which does not match any
3991 existing files is left untouched rather than causing an error.
3992 It is still an error for the substitution to be
3993 malformed, e.g., `echo [' still gives an error.
3994 .TP 8
3995 .B nostat \fR(+)
3996 A list of directories (or glob-patterns which match directories; see
3997 \fBFilename substitution\fR) that should not be \fIstat\fR(2)ed during a
3998 completion operation.  This is usually used to exclude directories which
3999 take too much time to \fIstat\fR(2), for example \fI/afs\fR.
4000 .TP 8
4001 .B notify
4002 If set, the shell announces job completions asynchronously.
4003 The default is to present job completions just before printing a prompt.
4004 .TP 8
4005 .B oid \fR(+)
4006 The user's real organization ID.  (Domain/OS only)
4007 .TP 8
4008 .B owd \fR(+)
4009 The old working directory, equivalent to the `\-' used by \fIcd\fR and \fIpushd\fR.
4010 See also the \fBcwd\fR and \fBdirstack\fR shell variables.
4011 .TP 8
4012 .B padhour
4013 If set, enable the printing of padding '0' for hours, in 24 and 12 hour
4014 formats.  E.G.: 07:45:42 vs. 7:45:42
4015 .TP 8
4016 .B path
4017 A list of directories in which to look for executable commands.
4018 A null word specifies the current directory.
4019 If there is no \fBpath\fR variable then only full path names will execute.
4020 \fBpath\fR is set by the shell at startup from the \fBPATH\fR environment
4021 variable or, if \fBPATH\fR does not exist, to a system-dependent default
4022 something like `(/usr/local/bin /usr/bsd /bin /usr/bin .)'.
4023 The shell may put `.' first or last in \fBpath\fR or omit it entirely
4024 depending on how it was compiled; see the \fBversion\fR shell variable.
4025 A shell which is given neither the \fB\-c\fR nor the \fB\-t\fR option
4026 hashes the contents of the directories in \fBpath\fR after
4027 reading \fI~/.tcshrc\fR and each time \fBpath\fR is reset.
4028 If one adds a new command to a directory in \fBpath\fR while the shell
4029 is active, one may need to do a \fIrehash\fR for the shell to find it.
4030 .TP 8
4031 .B printexitvalue \fR(+)
4032 If set and an interactive program exits with a non-zero status, the shell
4033 prints `Exit \fBstatus\fR'.
4034 .TP 8
4035 .B prompt
4036 The string which is printed before reading each command from the terminal.
4037 \fBprompt\fR may include any of the following formatting sequences (+), which
4038 are replaced by the given information:
4039 .PP
4040 .RS +8
4041 .PD 0
4042 .TP 4
4043 %/
4044 The current working directory.
4045 .TP 4
4046 %~
4047 The current working directory, but with one's home directory
4048 represented by `~' and other users' home directories represented by
4049 `~user' as per \fBFilename substitution\fR.  `~user' substitution
4050 happens only if the shell has already used `~\fIuser\fR' in a pathname
4051 in the current session.
4052 .TP 4
4053 %c[[0]\fIn\fR], %.[[0]\fIn\fR]
4054 The trailing component of the current working directory, or \fIn\fR
4055 trailing components if a digit \fIn\fR is given.
4056 If \fIn\fR begins with `0', the number of skipped components precede
4057 the trailing component(s) in the format `/<\fIskipped\fR>trailing'.
4058 If the \fBellipsis\fR shell variable is set, skipped components
4059 are represented by an ellipsis so the whole becomes `...trailing'.
4060 `~' substitution is done as in `%~' above, but the `~' component
4061 is ignored when counting trailing components.
4062 .TP 4
4063 %C
4064 Like %c, but without `~' substitution.
4065 .TP 4
4066 %h, %!, !
4067 The current history event number.
4068 .TP 4
4069 %M
4070 The full hostname.
4071 .TP 4
4072 %m
4073 The hostname up to the first `.'.
4074 .TP 4
4075 %S (%s)
4076 Start (stop) standout mode.
4077 .TP 4
4078 %B (%b)
4079 Start (stop) boldfacing mode.
4080 .TP 4
4081 %U (%u)
4082 Start (stop) underline mode.
4083 .TP 4
4084 %t, %@
4085 The time of day in 12-hour AM/PM format.
4086 .TP 4
4087 %T
4088 Like `%t', but in 24-hour format (but see the \fBampm\fR shell variable).
4089 .TP 4
4090 %p
4091 The `precise' time of day in 12-hour AM/PM format, with seconds.
4092 .TP 4
4093 %P
4094 Like `%p', but in 24-hour format (but see the \fBampm\fR shell variable).
4095 .TP 4
4096 \e\fIc\fR
4097 \fIc\fR is parsed as in \fIbindkey\fR.
4098 .TP 4
4099 ^\fIc\fR
4100 \fIc\fR is parsed as in \fIbindkey\fR.
4101 .TP 4
4102 %%
4103 A single `%'.
4104 .TP 4
4105 %n
4106 The user name.
4107 .TP 4
4108 %j
4109 The number of jobs.
4110 .TP 4
4111 %d
4112 The weekday in `Day' format.
4113 .TP 4
4114 %D
4115 The day in `dd' format.
4116 .TP 4
4117 %w
4118 The month in `Mon' format.
4119 .TP 4
4120 %W
4121 The month in `mm' format.
4122 .TP 4
4123 %y
4124 The year in `yy' format.
4125 .TP 4
4126 %Y
4127 The year in `yyyy' format.
4128 .TP 4
4129 %l
4130 The shell's tty.
4131 .TP 4
4132 %L
4133 Clears from the end of the prompt to end of the display or the end of the line.
4134 .TP 4
4135 %$
4136 Expands the shell or environment variable name immediately after the `$'.
4137 .TP 4
4138 %#
4139 `>' (or the first character of the \fBpromptchars\fR shell variable)
4140 for normal users, `#' (or the second character of \fBpromptchars\fR)
4141 for the superuser.
4142 .TP 4
4143 %{\fIstring\fR%}
4144 Includes \fIstring\fR as a literal escape sequence.
4145 It should be used only to change terminal attributes and
4146 should not move the cursor location.  This
4147 cannot be the last sequence in \fBprompt\fR.
4148 .TP 4
4149 %?
4150 The return code of the command executed just before the prompt.
4151 .TP 4
4152 %R
4153 In \fBprompt2\fR, the status of the parser.
4154 In \fBprompt3\fR, the corrected string.
4155 In \fBhistory\fR, the history string.
4156 .PD
4157 .PP
4158 `%B', `%S', `%U' and `%{\fIstring\fR%}' are available in only
4159 eight-bit-clean shells; see the \fBversion\fR shell variable.
4160 .PP
4161 The bold, standout and underline sequences are often used to distinguish a
4162 superuser shell.  For example,
4163 .IP "" 4
4164 > set prompt = "%m [%h] %B[%@]%b [%/] you rang? "
4165 .br
4166 tut [37] \fB[2:54pm]\fR [/usr/accts/sys] you rang? _
4167 .PP
4168 If `%t', `%@', `%T', `%p', or `%P' is used, and \fBnoding\fR is not set,
4169 then print `DING!' on the change of hour (i.e, `:00' minutes) instead of
4170 the actual time.
4171 .PP
4172 Set by default to `%# ' in interactive shells.
4173 .RE
4174 .TP 8
4175 .B prompt2 \fR(+)
4176 The string with which to prompt in \fIwhile\fR and \fIforeach\fR loops and
4177 after lines ending in `\\'.
4178 The same format sequences may be used as in \fBprompt\fR (q.v.);
4179 note the variable meaning of `%R'.
4180 Set by default to `%R? ' in interactive shells.
4181 .TP 8
4182 .B prompt3 \fR(+)
4183 The string with which to prompt when confirming automatic spelling correction.
4184 The same format sequences may be used as in \fBprompt\fR (q.v.);
4185 note the variable meaning of `%R'.
4186 Set by default to `CORRECT>%R (y|n|e|a)? ' in interactive shells.
4187 .TP 8
4188 .B promptchars \fR(+)
4189 If set (to a two-character string), the `%#' formatting sequence in the
4190 \fBprompt\fR shell variable is replaced with the first character for
4191 normal users and the second character for the superuser.
4192 .TP 8
4193 .B pushdtohome \fR(+)
4194 If set, \fIpushd\fR without arguments does `pushd ~', like \fIcd\fR.
4195 .TP 8
4196 .B pushdsilent \fR(+)
4197 If set, \fIpushd\fR and \fIpopd\fR do not print the directory stack.
4198 .TP 8
4199 .B recexact \fR(+)
4200 If set, completion completes on an exact match even if a longer match is
4201 possible.
4202 .TP 8
4203 .B recognize_only_executables \fR(+)
4204 If set, command listing displays only files in the path that are
4205 executable.  Slow.
4206 .TP 8
4207 .B rmstar \fR(+)
4208 If set, the user is prompted before `rm *' is executed.
4209 .TP 8
4210 .B rprompt \fR(+)
4211 The string to print on the right-hand side of the screen (after
4212 the command input) when the prompt is being displayed on the left.
4213 It recognizes the same formatting characters as \fBprompt\fR.
4214 It will automatically disappear and reappear as necessary, to ensure that
4215 command input isn't obscured, and will appear only if the prompt,
4216 command input, and itself will fit together on the first line.
4217 If \fBedit\fR isn't set, then \fBrprompt\fR will be printed after
4218 the prompt and before the command input.
4219 .TP 8
4220 .B savedirs \fR(+)
4221 If set, the shell does `dirs \-S' before exiting.
4222 If the first word is set to a number, at most that many directory stack
4223 entries are saved.
4224 .TP 8
4225 .B savehist
4226 If set, the shell does `history \-S' before exiting.
4227 If the first word is set to a number, at most that many lines are saved.
4228 (The number must be less than or equal to \fBhistory\fR.)
4229 If the second word is set to `merge', the history list is merged with
4230 the existing history file instead of replacing it (if there is one) and
4231 sorted by time stamp and the most recent events are retained.  (+)
4232 .TP 8
4233 .B sched \fR(+)
4234 The format in which the \fIsched\fR builtin command prints scheduled events;
4235 if not given, `%h\\t%T\\t%R\\n' is used.
4236 The format sequences are described above under \fBprompt\fR;
4237 note the variable meaning of `%R'.
4238 .TP 8
4239 .B shell
4240 The file in which the shell resides.  This is used in forking
4241 shells to interpret files which have execute bits set, but
4242 which are not executable by the system.  (See the description
4243 of \fBBuiltin and non-builtin command execution\fR.)  Initialized to the
4244 (system-dependent) home of the shell.
4245 .TP 8
4246 .B shlvl \fR(+)
4247 The number of nested shells.
4248 Reset to 1 in login shells.
4249 See also \fBloginsh\fR.
4250 .TP 8
4251 .B status
4252 The status returned by the last command.  If it terminated
4253 abnormally, then 0200 is added to the status.  Builtin commands
4254 which fail return exit status `1', all other builtin commands
4255 return status `0'.
4256 .TP 8
4257 .B symlinks \fR(+)
4258 Can be set to several different values to control symbolic link (`symlink')
4259 resolution:
4260 .RS +8
4261 .PP
4262 If set to `chase', whenever the current directory changes to a directory
4263 containing a symbolic link, it is expanded to the real name of the directory
4264 to which the link points.  This does not work for the user's home directory;
4265 this is a bug.
4266 .PP
4267 If set to `ignore', the shell tries to construct a current directory
4268 relative to the current directory before the link was crossed.
4269 This means that \fIcd\fRing through a symbolic link and then `cd ..'ing
4270 returns one to the original directory.  This affects only builtin commands
4271 and filename completion.
4272 .PP
4273 If set to `expand', the shell tries to fix symbolic links by actually expanding
4274 arguments which look like path names.  This affects any command, not just
4275 builtins.  Unfortunately, this does not work for hard-to-recognize filenames,
4276 such as those embedded in command options.  Expansion may be prevented by
4277 quoting.  While this setting is usually the most convenient, it is sometimes
4278 misleading and sometimes confusing when it fails to recognize an argument
4279 which should be expanded.  A compromise is to use `ignore' and use the
4280 editor command \fInormalize-path\fR (bound by default to ^X-n) when necessary.
4281 .PP
4282 Some examples are in order.  First, let's set up some play directories:
4283 .IP "" 4
4284 > cd /tmp
4285 .br
4286 > mkdir from from/src to
4287 .br
4288 > ln \-s from/src to/dst
4289 .PP
4290 Here's the behavior with \fBsymlinks\fR unset,
4291 .IP "" 4
4292 > cd /tmp/to/dst; echo $cwd
4293 .br
4294 /tmp/to/dst
4295 .br
4296 > cd ..; echo $cwd
4297 .br
4298 /tmp/from
4299 .PP
4300 here's the behavior with \fBsymlinks\fR set to `chase',
4301 .IP "" 4
4302 > cd /tmp/to/dst; echo $cwd
4303 .br
4304 /tmp/from/src
4305 .br
4306 > cd ..; echo $cwd
4307 .br
4308 /tmp/from
4309 .PP
4310 here's the behavior with \fBsymlinks\fR set to `ignore',
4311 .IP "" 4
4312 > cd /tmp/to/dst; echo $cwd
4313 .br
4314 /tmp/to/dst
4315 .br
4316 > cd ..; echo $cwd
4317 .br
4318 /tmp/to
4319 .PP
4320 and here's the behavior with \fBsymlinks\fR set to `expand'.
4321 .IP "" 4
4322 > cd /tmp/to/dst; echo $cwd
4323 .br
4324 /tmp/to/dst
4325 .br
4326 > cd ..; echo $cwd
4327 .br
4328 /tmp/to
4329 .br
4330 > cd /tmp/to/dst; echo $cwd
4331 .br
4332 /tmp/to/dst
4333 .br
4334 > cd ".."; echo $cwd
4335 .br
4336 /tmp/from
4337 .br
4338 > /bin/echo ..
4339 .br
4340 /tmp/to
4341 .br
4342 > /bin/echo ".."
4343 .br
4344 \&..
4345 .PP
4346 Note that `expand' expansion 1) works just like `ignore' for builtins
4347 like \fIcd\fR, 2) is prevented by quoting, and 3) happens before
4348 filenames are passed to non-builtin commands.
4349 .RE
4350 .TP 8
4351 .B tcsh \fR(+)
4352 The version number of the shell in the format `R.VV.PP',
4353 where `R' is the major release number, `VV' the current version
4354 and `PP' the patchlevel.
4355 .TP 8
4356 .B term
4357 The terminal type.  Usually set in \fI~/.login\fR as described under
4358 \fBStartup and shutdown\fR.
4359 .TP 8
4360 .B time
4361 If set to a number, then the \fItime\fR builtin (q.v.) executes automatically
4362 after each command which takes more than that many CPU seconds.
4363 If there is a second word, it is used as a format string for the output
4364 of the \fItime\fR builtin.  (u) The following sequences may be used in the
4365 format string:
4366 .PP
4367 .RS +8
4368 .PD 0
4369 .TP 4
4370 %U
4371 The time the process spent in user mode in cpu seconds.
4372 .TP 4
4373 %S
4374 The time the process spent in kernel mode in cpu seconds.
4375 .TP 4
4376 %E
4377 The elapsed (wall clock) time in seconds.
4378 .TP 4
4379 %P
4380 The CPU percentage computed as (%U + %S) / %E.
4381 .TP 4
4382 %W
4383 Number of times the process was swapped.
4384 .TP 4
4385 %X
4386 The average amount in (shared) text space used in Kbytes.
4387 .TP 4
4388 %D
4389 The average amount in (unshared) data/stack space used in Kbytes.
4390 .TP 4
4391 %K
4392 The total space used (%X + %D) in Kbytes.
4393 .TP 4
4394 %M
4395 The maximum memory the process had in use at any time in Kbytes.
4396 .TP 4
4397 %F
4398 The number of major page faults (page needed to be brought from disk).
4399 .TP 4
4400 %R
4401 The number of minor page faults.
4402 .TP 4
4403 %I
4404 The number of input operations.
4405 .TP 4
4406 %O
4407 The number of output operations.
4408 .TP 4
4409 %r
4410 The number of socket messages received.
4411 .TP 4
4412 %s
4413 The number of socket messages sent.
4414 .TP 4
4415 %k
4416 The number of signals received.
4417 .TP 4
4418 %w
4419 The number of voluntary context switches (waits).
4420 .TP 4
4421 %c
4422 The number of involuntary context switches.
4423 .PD
4424 .PP
4425 Only the first four sequences are supported on systems without BSD resource
4426 limit functions.
4427 The default time format is `%Uu %Ss %E %P %X+%Dk %I+%Oio %Fpf+%Ww' for
4428 systems that support resource usage reporting and `%Uu %Ss %E %P' for
4429 systems that do not.
4430 .PP
4431 Under Sequent's DYNIX/ptx, %X, %D, %K, %r and %s are not
4432 available, but the following additional sequences are:
4433 .PP
4434 .PD 0
4435 .TP 4
4436 %Y
4437 The number of system calls performed.
4438 .TP 4
4439 %Z
4440 The number of pages which are zero-filled on demand.
4441 .TP 4
4442 %i
4443 The number of times a process's resident set size was increased by the kernel.
4444 .TP 4
4445 %d
4446 The number of times a process's resident set size was decreased by the kernel.
4447 .TP 4
4448 %l
4449 The number of read system calls performed.
4450 .TP 4
4451 %m
4452 The number of write system calls performed.
4453 .TP 4
4454 %p
4455 The number of reads from raw disk devices.
4456 .TP 4
4457 %q
4458 The number of writes to raw disk devices.
4459 .PD
4460 .PP
4461 and the default time format is `%Uu %Ss %E %P %I+%Oio %Fpf+%Ww'.
4462 Note that the CPU percentage can be higher than 100% on multi-processors.
4463 .RE
4464 .TP 8
4465 .B tperiod \fR(+)
4466 The period, in minutes, between executions of the \fIperiodic\fR special alias.
4467 .TP 8
4468 .B tty \fR(+)
4469 The name of the tty, or empty if not attached to one.
4470 .TP 8
4471 .B uid \fR(+)
4472 The user's real user ID.
4473 .TP 8
4474 .B user
4475 The user's login name.
4476 .TP 8
4477 .B verbose
4478 If set, causes the words of each
4479 command to be printed, after history substitution (if any).
4480 Set by the \fB\-v\fR command line option.
4481 .TP 8
4482 .B version \fR(+)
4483 The version ID stamp.  It contains the shell's version number (see \fBtcsh\fR),
4484 origin, release date, vendor, operating system and machine (see \fBVENDOR\fR,
4485 \fBOSTYPE\fR and \fBMACHTYPE\fR) and a comma-separated
4486 list of options which were set at compile time.
4487 Options which are set by default in the distribution are noted.
4488 .PP
4489 .RS +8
4490 .PD 0
4491 .TP 6
4492 8b
4493 The shell is eight bit clean; default
4494 .TP 6
4495 7b
4496 The shell is not eight bit clean
4497 .TP 6
4498 wide
4499 The shell is multibyte encoding clean (like UTF-8)
4500 .TP 6
4501 nls
4502 The system's NLS is used; default for systems with NLS
4503 .TP 6
4504 lf
4505 Login shells execute \fI/etc/csh.login\fR before instead of after
4506 \fI/etc/csh.cshrc\fR and \fI~/.login\fR before instead of after
4507 \fI~/.tcshrc\fR and \fI~/.history\fR.
4508 .TP 6
4509 dl
4510 `.' is put last in \fBpath\fR for security; default
4511 .TP 6
4512 nd
4513 `.' is omitted from \fBpath\fR for security
4514 .TP 6
4515 vi
4516 \fIvi\fR-style editing is the default rather than \fIemacs\fR
4517 .TP 6
4518 dtr
4519 Login shells drop DTR when exiting
4520 .TP 6
4521 bye
4522 \fIbye\fR is a synonym for \fIlogout\fR and \fIlog\fR
4523 is an alternate name for \fIwatchlog\fR
4524 .TP 6
4525 al
4526 \fBautologout\fR is enabled; default
4527 .TP 6
4528 kan
4529 Kanji is used if appropriate according to locale settings,
4530 unless the \fBnokanji\fR shell variable is set
4531 .TP 6
4532 sm
4533 The system's \fImalloc\fR(3) is used
4534 .TP 6
4535 hb
4536 The `#!<program> <args>' convention is emulated when executing shell scripts
4537 .TP 6
4538 ng
4539 The \fInewgrp\fR builtin is available
4540 .TP 6
4541 rh
4542 The shell attempts to set the \fBREMOTEHOST\fR environment variable
4543 .TP 6
4544 afs
4545 The shell verifies your password with the kerberos server if local
4546 authentication fails.  The \fBafsuser\fR shell variable or the
4547 \fBAFSUSER\fR environment variable override your local username if set.
4548 .PD
4549 .PP
4550 An administrator may enter additional strings to indicate differences
4551 in the local version.
4552 .RE
4553 .TP 8
4554 .B visiblebell \fR(+)
4555 If set, a screen flash is used rather than the audible bell.
4556 See also \fBnobeep\fR.
4557 .TP 8
4558 .B watch \fR(+)
4559 A list of user/terminal pairs to watch for logins and logouts.
4560 If either the user is `any' all terminals are watched for the given user
4561 and vice versa.
4562 Setting \fBwatch\fR to `(any any)' watches all users and terminals.
4563 For example,
4564 .RS +8
4565 .IP "" 4
4566 set watch = (george ttyd1 any console $user any)
4567 .PP
4568 reports activity of the user `george' on ttyd1, any user on the console, and
4569 oneself (or a trespasser) on any terminal.
4570 .PP
4571 Logins and logouts are checked every 10 minutes by default, but the first
4572 word of \fBwatch\fR can be set to a number to check every so many minutes.
4573 For example,
4574 .IP "" 4
4575 set watch = (1 any any)
4576 .PP
4577 reports any login/logout once every minute.  For the impatient, the \fIlog\fR
4578 builtin command triggers a \fBwatch\fR report at any time.  All current logins
4579 are reported (as with the \fIlog\fR builtin) when \fBwatch\fR is first set.
4580 .PP
4581 The \fBwho\fR shell variable controls the format of \fBwatch\fR reports.
4582 .RE
4583 .TP 8
4584 .B who \fR(+)
4585 The format string for \fBwatch\fR messages.  The following sequences
4586 are replaced by the given information:
4587 .PP
4588 .RS +8
4589 .PD 0
4590 .TP 4
4591 %n
4592 The name of the user who logged in/out.
4593 .TP 4
4594 %a
4595 The observed action, i.e., `logged on', `logged off' or `replaced \fIolduser\fR on'.
4596 .TP 4
4597 %l
4598 The terminal (tty) on which the user logged in/out.
4599 .TP 4
4600 %M
4601 The full hostname of the remote host, or `local' if the login/logout was
4602 from the local host.
4603 .TP 4
4604 %m
4605 The hostname of the remote host up to the first `.'.
4606 The full name is printed if it is an IP address or an X Window System display.
4607 .PD
4608 .PP
4609 %M and %m are available on only systems that store the remote hostname in
4610 \fI/etc/utmp\fR.
4611 If unset, `%n has %a %l from %m.' is used, or `%n has %a %l.' on systems
4612 which don't store the remote hostname.
4613 .RE
4614 .TP 8
4615 .B wordchars \fR(+)
4616 A list of non-alphanumeric characters to be considered part of a word by the
4617 \fIforward-word\fR, \fIbackward-word\fR etc., editor commands.