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. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgment:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" Style notes for the tcsh man page:
33.\"
34.\" - Tags in lists are bold, except in the FILES section where they are
35.\" italic.
36.\"
37.\" - References are bold for section headings and environment and shell
38.\" variables and italic for commands (externals, builtins, aliases, and
39.\" editor commands) and arguments to commands.
40.\"
41.\" - Be careful with the .B and .I macros: they handle only a limited number
42.\" of words. Work around this with \fB and \fI, but only if absolutely
43.\" necessary, because tcsh.man2html uses .B/.I to find name anchors.
44.\"
45.\" - Indent in multiples of 4, usually 8.
46.\"
47.\" - Use `', not '' or "", except of course in shell syntax examples.
48.\" '' at the beginning of a line will vanish!
49.\"
50.\" - Use \-, not -.
51.\"
52.\" - Include the tilde when naming dot files. `~/.login', not `.login'.
53.\"
54.\" - Refer to external commands in man page format, e.g., `csh(1)'. However,
55.\" tcsh is `tcsh', not `tcsh(1)', because this is the tcsh man page (and
56.\" see the next note anyway).
57.\"
58.\" - Say `the shell', not `tcsh', unless distinguishing between tcsh and csh.
59.\"
60.\" - Say `shell variable'/`environment variable' instead of `variable'
61.\" and `builtin command'/`editor command' instead of `builtin' or `command'
62.\" unless the distinction is absolutely clear from context.
63.\"
64.\" - Use the simple present tense. `The shell uses', not `The shell will use'.
65.\"
66.\" - IMPORTANT: Cross-reference as much as possible. Commands, variables,
67.\" etc. in the reference section should be mentioned in the appropriate
68.\" descriptive section, or at least in the reference-section description
69.\" of another command (or whatever) which is mentioned in a description
70.\" section. Remember to note OS-specific things in "OS variant support",
71.\" new features in NEW FEATURES and referenced external commands in SEE
72.\" ALSO.
73.\"
74.\" - tcsh.man2html depends heavily on the specific nroff commands used in the
75.\" man page when the script was written. Please stick closely to the style
76.\" used here if you can. In particular, please don't use nroff commands
77.\" which aren't already used herein.
78.\"
| 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. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgment:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" Style notes for the tcsh man page:
33.\"
34.\" - Tags in lists are bold, except in the FILES section where they are
35.\" italic.
36.\"
37.\" - References are bold for section headings and environment and shell
38.\" variables and italic for commands (externals, builtins, aliases, and
39.\" editor commands) and arguments to commands.
40.\"
41.\" - Be careful with the .B and .I macros: they handle only a limited number
42.\" of words. Work around this with \fB and \fI, but only if absolutely
43.\" necessary, because tcsh.man2html uses .B/.I to find name anchors.
44.\"
45.\" - Indent in multiples of 4, usually 8.
46.\"
47.\" - Use `', not '' or "", except of course in shell syntax examples.
48.\" '' at the beginning of a line will vanish!
49.\"
50.\" - Use \-, not -.
51.\"
52.\" - Include the tilde when naming dot files. `~/.login', not `.login'.
53.\"
54.\" - Refer to external commands in man page format, e.g., `csh(1)'. However,
55.\" tcsh is `tcsh', not `tcsh(1)', because this is the tcsh man page (and
56.\" see the next note anyway).
57.\"
58.\" - Say `the shell', not `tcsh', unless distinguishing between tcsh and csh.
59.\"
60.\" - Say `shell variable'/`environment variable' instead of `variable'
61.\" and `builtin command'/`editor command' instead of `builtin' or `command'
62.\" unless the distinction is absolutely clear from context.
63.\"
64.\" - Use the simple present tense. `The shell uses', not `The shell will use'.
65.\"
66.\" - IMPORTANT: Cross-reference as much as possible. Commands, variables,
67.\" etc. in the reference section should be mentioned in the appropriate
68.\" descriptive section, or at least in the reference-section description
69.\" of another command (or whatever) which is mentioned in a description
70.\" section. Remember to note OS-specific things in "OS variant support",
71.\" new features in NEW FEATURES and referenced external commands in SEE
72.\" ALSO.
73.\"
74.\" - tcsh.man2html depends heavily on the specific nroff commands used in the
75.\" man page when the script was written. Please stick closely to the style
76.\" used here if you can. In particular, please don't use nroff commands
77.\" which aren't already used herein.
78.\"
|
79.TH TCSH 1 "19 November 2000" "Astron 6.10.00"
| 79.TH TCSH 1 "2 September 2001" "Astron 6.11.00"
|
80.SH NAME
81tcsh \- C shell with file name completion and command line editing
82.SH SYNOPSIS
83.B tcsh \fR[\fB\-bcdefFimnqstvVxX\fR] [\fB\-Dname\fR[\fB=value\fR]] [arg ...]
84.br
85.B tcsh \-l
86.SH DESCRIPTION
87\fItcsh\fR is an enhanced but completely compatible version of the Berkeley
88UNIX C shell, \fIcsh\fR(1).
89It is a command language interpreter usable both as an interactive login
90shell and a shell script command processor.
91It includes a command-line editor (see \fBThe command-line editor\fR),
92programmable word completion (see \fBCompletion and listing\fR),
93spelling correction (see \fBSpelling correction\fR),
94a history mechanism (see \fBHistory substitution\fR),
95job control (see \fBJobs\fR)
96and a C-like syntax.
97The \fBNEW FEATURES\fR section describes major enhancements of \fItcsh\fR
98over \fIcsh\fR(1).
99Throughout this manual, features of
100\fItcsh\fR not found in most \fIcsh\fR(1) implementations
101(specifically, the 4.4BSD \fIcsh\fR)
102are labeled with `(+)', and features which are present in \fIcsh\fR(1)
103but not usually documented are labeled with `(u)'.
104.SS "Argument list processing"
105If the first argument (argument 0) to the shell is `\-' then it is a
106login shell. A login shell can be also specified by invoking the shell with
107the \fB\-l\fR flag as the only argument.
108.PP
109The rest of the flag arguments are interpreted as follows:
110.TP 4
111.B \-b
112Forces a ``break'' from option processing, causing any
113further shell arguments to be treated as non-option arguments. The remaining
114arguments will not be interpreted as shell options. This may be used to pass
115options to a shell script without confusion or possible subterfuge. The shell
116will not run a set-user ID script without this option.
117.TP 4
118.B \-c
119Commands are read from the following argument (which must be present, and
120must be a single argument),
121stored in the \fBcommand\fR shell variable for reference, and executed.
122Any remaining arguments are placed in the \fBargv\fR shell variable.
123.TP 4
124.B \-d
125The shell loads the directory stack from \fI~/.cshdirs\fR as described under
126\fBStartup and shutdown\fR, whether or not it is a login shell. (+)
127.TP 4
128.B \-D\fIname\fR[=\fIvalue\fR]
129Sets the environment variable \fIname\fR to \fIvalue\fR. (Domain/OS only) (+)
130.TP 4
131.B \-e
132The shell exits if any invoked command terminates abnormally or
133yields a non-zero exit status.
134.TP 4
135.B \-f
136The shell ignores \fI~/.tcshrc\fR, and thus starts faster.
137.TP 4
138.B \-F
139The shell uses \fIfork\fR(2) instead of \fIvfork\fR(2) to spawn processes. (Convex/OS only) (+)
140.TP 4
141.B \-i
142The shell is interactive and prompts for its top-level input, even if
143it appears to not be a terminal. Shells are interactive without this option if
144their inputs and outputs are terminals.
145.TP 4
146.B \-l
147The shell is a login shell. Applicable only if \fB\-l\fR is the only
148flag specified.
149.TP 4
150.B \-m
151The shell loads \fI~/.tcshrc\fR even if it does not belong to the effective
152user. Newer versions of \fIsu\fR(1) can pass \fB\-m\fR to the shell. (+)
153.TP 4
154.B \-n
155The shell parses commands but does not execute them.
156This aids in debugging shell scripts.
157.TP 4
158.B \-q
159The shell accepts SIGQUIT (see \fBSignal handling\fR) and behaves when
160it is used under a debugger. Job control is disabled. (u)
161.TP 4
162.B \-s
163Command input is taken from the standard input.
164.TP 4
165.B \-t
166The shell reads and executes a single line of input. A `\\' may be used to
167escape the newline at the end of this line and continue onto another line.
168.TP 4
169.B \-v
170Sets the \fBverbose\fR shell variable, so that
171command input is echoed after history substitution.
172.TP 4
173.B \-x
174Sets the \fBecho\fR shell variable, so that commands are echoed
175immediately before execution.
176.TP 4
177.B \-V
178Sets the \fBverbose\fR shell variable even before executing \fI~/.tcshrc\fR.
179.TP 4
180.B \-X
181Is to \fB\-x\fR as \fB\-V\fR is to \fB\-v\fR.
182.PP
183After processing of flag arguments, if arguments remain but none of the
184\fB\-c\fR, \fB\-i\fR, \fB\-s\fR, or \fB\-t\fR options were given, the first
185argument is taken as the name of a file of commands, or ``script'', to
186be executed. The shell opens this file and saves its name for possible
187resubstitution by `$0'. Because many systems use either the standard
188version 6 or version 7 shells whose shell scripts are not compatible
189with this shell, the shell uses such a `standard' shell to execute a script
190whose first character is not a `#', i.e., that does not start with a
191comment.
192.PP
193Remaining arguments are placed in the \fBargv\fR shell variable.
194.SS "Startup and shutdown"
195A login shell begins by executing commands from the system files
196\fI/etc/csh.cshrc\fR and \fI/etc/csh.login\fR.
197It then executes commands from files in the user's \fBhome\fR directory:
198first \fI~/.tcshrc\fR (+)
199or, if \fI~/.tcshrc\fR is not found, \fI~/.cshrc\fR,
200then \fI~/.history\fR (or the value of the \fBhistfile\fR shell variable),
201then \fI~/.login\fR,
202and finally \fI~/.cshdirs\fR (or the value of the \fBdirsfile\fR shell variable) (+).
203The shell may read \fI/etc/csh.login\fR before instead of after
204\fI/etc/csh.cshrc\fR, and \fI~/.login\fR before instead of after
205\fI~/.tcshrc\fR or \fI~/.cshrc\fR and \fI~/.history\fR, if so compiled;
206see the \fBversion\fR shell variable. (+)
207.PP
208Non-login shells read only \fI/etc/csh.cshrc\fR and \fI~/.tcshrc\fR
209or \fI~/.cshrc\fR on startup.
210.PP
| 80.SH NAME
81tcsh \- C shell with file name completion and command line editing
82.SH SYNOPSIS
83.B tcsh \fR[\fB\-bcdefFimnqstvVxX\fR] [\fB\-Dname\fR[\fB=value\fR]] [arg ...]
84.br
85.B tcsh \-l
86.SH DESCRIPTION
87\fItcsh\fR is an enhanced but completely compatible version of the Berkeley
88UNIX C shell, \fIcsh\fR(1).
89It is a command language interpreter usable both as an interactive login
90shell and a shell script command processor.
91It includes a command-line editor (see \fBThe command-line editor\fR),
92programmable word completion (see \fBCompletion and listing\fR),
93spelling correction (see \fBSpelling correction\fR),
94a history mechanism (see \fBHistory substitution\fR),
95job control (see \fBJobs\fR)
96and a C-like syntax.
97The \fBNEW FEATURES\fR section describes major enhancements of \fItcsh\fR
98over \fIcsh\fR(1).
99Throughout this manual, features of
100\fItcsh\fR not found in most \fIcsh\fR(1) implementations
101(specifically, the 4.4BSD \fIcsh\fR)
102are labeled with `(+)', and features which are present in \fIcsh\fR(1)
103but not usually documented are labeled with `(u)'.
104.SS "Argument list processing"
105If the first argument (argument 0) to the shell is `\-' then it is a
106login shell. A login shell can be also specified by invoking the shell with
107the \fB\-l\fR flag as the only argument.
108.PP
109The rest of the flag arguments are interpreted as follows:
110.TP 4
111.B \-b
112Forces a ``break'' from option processing, causing any
113further shell arguments to be treated as non-option arguments. The remaining
114arguments will not be interpreted as shell options. This may be used to pass
115options to a shell script without confusion or possible subterfuge. The shell
116will not run a set-user ID script without this option.
117.TP 4
118.B \-c
119Commands are read from the following argument (which must be present, and
120must be a single argument),
121stored in the \fBcommand\fR shell variable for reference, and executed.
122Any remaining arguments are placed in the \fBargv\fR shell variable.
123.TP 4
124.B \-d
125The shell loads the directory stack from \fI~/.cshdirs\fR as described under
126\fBStartup and shutdown\fR, whether or not it is a login shell. (+)
127.TP 4
128.B \-D\fIname\fR[=\fIvalue\fR]
129Sets the environment variable \fIname\fR to \fIvalue\fR. (Domain/OS only) (+)
130.TP 4
131.B \-e
132The shell exits if any invoked command terminates abnormally or
133yields a non-zero exit status.
134.TP 4
135.B \-f
136The shell ignores \fI~/.tcshrc\fR, and thus starts faster.
137.TP 4
138.B \-F
139The shell uses \fIfork\fR(2) instead of \fIvfork\fR(2) to spawn processes. (Convex/OS only) (+)
140.TP 4
141.B \-i
142The shell is interactive and prompts for its top-level input, even if
143it appears to not be a terminal. Shells are interactive without this option if
144their inputs and outputs are terminals.
145.TP 4
146.B \-l
147The shell is a login shell. Applicable only if \fB\-l\fR is the only
148flag specified.
149.TP 4
150.B \-m
151The shell loads \fI~/.tcshrc\fR even if it does not belong to the effective
152user. Newer versions of \fIsu\fR(1) can pass \fB\-m\fR to the shell. (+)
153.TP 4
154.B \-n
155The shell parses commands but does not execute them.
156This aids in debugging shell scripts.
157.TP 4
158.B \-q
159The shell accepts SIGQUIT (see \fBSignal handling\fR) and behaves when
160it is used under a debugger. Job control is disabled. (u)
161.TP 4
162.B \-s
163Command input is taken from the standard input.
164.TP 4
165.B \-t
166The shell reads and executes a single line of input. A `\\' may be used to
167escape the newline at the end of this line and continue onto another line.
168.TP 4
169.B \-v
170Sets the \fBverbose\fR shell variable, so that
171command input is echoed after history substitution.
172.TP 4
173.B \-x
174Sets the \fBecho\fR shell variable, so that commands are echoed
175immediately before execution.
176.TP 4
177.B \-V
178Sets the \fBverbose\fR shell variable even before executing \fI~/.tcshrc\fR.
179.TP 4
180.B \-X
181Is to \fB\-x\fR as \fB\-V\fR is to \fB\-v\fR.
182.PP
183After processing of flag arguments, if arguments remain but none of the
184\fB\-c\fR, \fB\-i\fR, \fB\-s\fR, or \fB\-t\fR options were given, the first
185argument is taken as the name of a file of commands, or ``script'', to
186be executed. The shell opens this file and saves its name for possible
187resubstitution by `$0'. Because many systems use either the standard
188version 6 or version 7 shells whose shell scripts are not compatible
189with this shell, the shell uses such a `standard' shell to execute a script
190whose first character is not a `#', i.e., that does not start with a
191comment.
192.PP
193Remaining arguments are placed in the \fBargv\fR shell variable.
194.SS "Startup and shutdown"
195A login shell begins by executing commands from the system files
196\fI/etc/csh.cshrc\fR and \fI/etc/csh.login\fR.
197It then executes commands from files in the user's \fBhome\fR directory:
198first \fI~/.tcshrc\fR (+)
199or, if \fI~/.tcshrc\fR is not found, \fI~/.cshrc\fR,
200then \fI~/.history\fR (or the value of the \fBhistfile\fR shell variable),
201then \fI~/.login\fR,
202and finally \fI~/.cshdirs\fR (or the value of the \fBdirsfile\fR shell variable) (+).
203The shell may read \fI/etc/csh.login\fR before instead of after
204\fI/etc/csh.cshrc\fR, and \fI~/.login\fR before instead of after
205\fI~/.tcshrc\fR or \fI~/.cshrc\fR and \fI~/.history\fR, if so compiled;
206see the \fBversion\fR shell variable. (+)
207.PP
208Non-login shells read only \fI/etc/csh.cshrc\fR and \fI~/.tcshrc\fR
209or \fI~/.cshrc\fR on startup.
210.PP
|
| 211For examples of startup files, please consult
212\fIhttp://tcshrc.sourceforge.net\fR.
213.PP
|
211Commands like \fIstty\fR(1) and \fItset\fR(1),
212which need be run only once per login, usually go in one's \fI~/.login\fR file.
213Users who need to use the same set of files with both \fIcsh\fR(1) and
214\fItcsh\fR can have only a \fI~/.cshrc\fR which checks for the existence of the
215\fBtcsh\fR shell variable (q.v.) before using \fItcsh\fR-specific commands,
216or can have both a \fI~/.cshrc\fR and a \fI~/.tcshrc\fR which \fIsource\fRs
217(see the builtin command) \fI~/.cshrc\fR.
218The rest of this manual uses `\fI~/.tcshrc\fR' to mean `\fI~/.tcshrc\fR or,
219if \fI~/.tcshrc\fR is not found, \fI~/.cshrc\fR'.
220.PP
221In the normal case, the shell begins reading commands from the terminal,
222prompting with `> '. (Processing of arguments and the use of the shell to
223process files containing command scripts are described later.)
224The shell repeatedly reads a line of command input, breaks it into words,
225places it on the command history list, parses it and executes each command
226in the line.
227.PP
228One can log out by typing `^D' on an empty line, `logout' or `login' or
229via the shell's autologout mechanism (see the \fBautologout\fR shell variable).
230When a login shell terminates it sets the \fBlogout\fR shell variable to
231`normal' or `automatic' as appropriate, then
232executes commands from the files
233\fI/etc/csh.logout\fR and \fI~/.logout\fR. The shell may drop DTR on logout
234if so compiled; see the \fBversion\fR shell variable.
235.PP
236The names of the system login and logout files vary from system to system for
237compatibility with different \fIcsh\fR(1) variants; see \fBFILES\fR.
238.SS Editing
239We first describe \fBThe command-line editor\fR.
240The \fBCompletion and listing\fR and \fBSpelling correction\fR sections
241describe two sets of functionality that are implemented as editor commands
242but which deserve their own treatment.
243Finally, \fBEditor commands\fR lists and describes
244the editor commands specific to the shell and their default bindings.
245.SS "The command-line editor (+)"
246Command-line input can be edited using key sequences much like those used in
247GNU Emacs or \fIvi\fR(1).
248The editor is active only when the \fBedit\fR shell variable is set, which
249it is by default in interactive shells.
250The \fIbindkey\fR builtin can display and change key bindings.
251Emacs-style key bindings are used by default
252(unless the shell was compiled otherwise; see the \fBversion\fR shell variable),
253but \fIbindkey\fR can change the key bindings to \fIvi\fR-style bindings en masse.
254.PP
255The shell always binds the arrow keys (as defined in the \fBTERMCAP\fR
256environment variable) to
257.PP
258.PD 0
259.RS +4
260.TP 8
261down
262\fIdown-history\fR
263.TP 8
264up
265\fIup-history\fR
266.TP 8
267left
268\fIbackward-char\fR
269.TP 8
270right
271\fIforward-char\fR
272.PD
273.RE
274.PP
275unless doing so would alter another single-character binding.
276One can set the arrow key escape sequences to the empty string with \fIsettc\fR
277to prevent these bindings.
278The ANSI/VT100 sequences for arrow keys are always bound.
279.PP
280Other key bindings are, for the most part, what Emacs and \fIvi\fR(1)
281users would expect and can easily be displayed by \fIbindkey\fR, so there
282is no need to list them here. Likewise, \fIbindkey\fR can list the editor
283commands with a short description of each.
284.PP
285Note that editor commands do not have the same notion of a ``word'' as does the
286shell. The editor delimits words with any non-alphanumeric characters not in
287the shell variable \fBwordchars\fR, while the shell recognizes only whitespace
288and some of the characters with special meanings to it, listed under
289\fBLexical structure\fR.
290.SS "Completion and listing (+)"
291The shell is often able to complete words when given a unique abbreviation.
292Type part of a word (for example `ls /usr/lost') and hit the tab key to
293run the \fIcomplete-word\fR editor command.
294The shell completes the filename `/usr/lost' to `/usr/lost+found/',
295replacing the incomplete word with the complete word in the input buffer.
296(Note the terminal `/'; completion adds a `/' to the
297end of completed directories and a space to the end of other completed words,
298to speed typing and provide a visual indicator of successful completion.
299The \fBaddsuffix\fR shell variable can be unset to prevent this.)
300If no match is found (perhaps `/usr/lost+found' doesn't exist),
301the terminal bell rings.
302If the word is already complete (perhaps there is a `/usr/lost' on your
303system, or perhaps you were thinking too far ahead and typed the whole thing)
304a `/' or space is added to the end if it isn't already there.
305.PP
306Completion works anywhere in the line, not at just the end; completed
307text pushes the rest of the line to the right. Completion in the middle of a word
308often results in leftover characters to the right of the cursor that need
309to be deleted.
310.PP
311Commands and variables can be completed in much the same way.
312For example, typing `em[tab]' would complete `em' to
313`emacs' if \fIemacs\fR were the only command on your system beginning with `em'.
314Completion can find a command in any directory in \fBpath\fR or if
315given a full pathname.
316Typing `echo $ar[tab]' would complete `$ar' to `$argv'
317if no other variable began with `ar'.
318.PP
319The shell parses the input buffer to determine whether the word you want to
320complete should be completed as a filename, command or variable.
321The first word in the buffer and the first word following
322`;', `|', `|&', `&&' or `||' is considered to be a command.
323A word beginning with `$' is considered to be a variable.
324Anything else is a filename. An empty line is `completed' as a filename.
325.PP
326You can list the possible completions of a word at any time by typing `^D'
327to run the \fIdelete-char-or-list-or-eof\fR editor command.
328The shell lists the possible completions using the \fIls\-F\fR builtin (q.v.)
329and reprints the prompt and unfinished command line, for example:
330.IP "" 4
331> ls /usr/l[^D]
332.br
333lbin/ lib/ local/ lost+found/
334.br
335> ls /usr/l
336.PP
337If the \fBautolist\fR shell variable is set, the shell lists the remaining
338choices (if any) whenever completion fails:
339.IP "" 4
340> set autolist
341.br
342> nm /usr/lib/libt[tab]
343.br
344libtermcap.a@ libtermlib.a@
345.br
346> nm /usr/lib/libterm
347.PP
348If \fBautolist\fR is set to `ambiguous', choices are listed only when
349completion fails and adds no new characters to the word being completed.
350.PP
351A filename to be completed can contain variables, your own or others' home
352directories abbreviated with `~' (see \fBFilename substitution\fR) and
353directory stack entries abbreviated with `='
354(see \fBDirectory stack substitution\fR). For example,
355.IP "" 4
356> ls ~k[^D]
357.br
358kahn kas kellogg
359.br
360> ls ~ke[tab]
361.br
362> ls ~kellogg/
363.PP
364or
365.IP "" 4
366> set local = /usr/local
367.br
368> ls $lo[tab]
369.br
370> ls $local/[^D]
371.br
372bin/ etc/ lib/ man/ src/
373.br
374> ls $local/
375.PP
376Note that variables can also be expanded explicitly with the
377\fIexpand-variables\fR editor command.
378.PP
379\fIdelete-char-or-list-or-eof\fR lists at only the end of the line;
380in the middle of a line it deletes the character under the cursor and
381on an empty line it logs one out or, if \fBignoreeof\fR is set, does nothing.
382`M-^D', bound to the editor command \fIlist-choices\fR, lists completion
383possibilities anywhere on a line, and \fIlist-choices\fR (or any one of the
384related editor commands that do or don't delete, list and/or log out,
385listed under \fIdelete-char-or-list-or-eof\fR) can be bound to `^D' with
386the \fIbindkey\fR builtin command if so desired.
387.PP
388The \fIcomplete-word-fwd\fR and \fIcomplete-word-back\fR editor commands
389(not bound to any keys by default) can be used to cycle up and down through
390the list of possible completions, replacing the current word with the next or
391previous word in the list.
392.PP
393The shell variable \fBfignore\fR can be set to a list of suffixes to be
394ignored by completion. Consider the following:
395.IP "" 4
396> ls
397.br
398Makefile condiments.h~ main.o side.c
399.br
400README main.c meal side.o
401.br
402condiments.h main.c~
403.br
404> set fignore = (.o \\~)
405.br
406> emacs ma[^D]
407.br
408main.c main.c~ main.o
409.br
410> emacs ma[tab]
411.br
412> emacs main.c
413.PP
414`main.c~' and `main.o' are ignored by completion (but not listing),
415because they end in suffixes in \fBfignore\fR.
416Note that a `\\' was needed in front of `~' to prevent it from being
417expanded to \fBhome\fR as described under \fBFilename substitution\fR.
418\fBfignore\fR is ignored if only one completion is possible.
419.PP
420If the \fBcomplete\fR shell variable is set to `enhance', completion
4211) ignores case and 2) considers periods, hyphens and underscores
422(`.', `\-' and `_') to be word separators and hyphens and underscores to
423be equivalent. If you had the following files
424.IP "" 4
425comp.lang.c comp.lang.perl comp.std.c++
426.br
427comp.lang.c++ comp.std.c
428.PP
429and typed `mail \-f c.l.c[tab]', it would be completed to
430`mail \-f comp.lang.c', and ^D would list `comp.lang.c' and `comp.lang.c++'.
431`mail \-f c..c++[^D]' would list `comp.lang.c++' and `comp.std.c++'. Typing
432`rm a\-\-file[^D]' in the following directory
433.IP "" 4
434A_silly_file a-hyphenated-file another_silly_file
435.PP
436would list all three files, because case is ignored and hyphens and
437underscores are equivalent. Periods, however, are not equivalent to
438hyphens or underscores.
439.PP
440Completion and listing are affected by several other shell variables:
441\fBrecexact\fR can be set to complete on the shortest possible unique
442match, even if more typing might result in a longer match:
443.IP "" 4
444> ls
445.br
446fodder foo food foonly
447.br
448> set recexact
449.br
450> rm fo[tab]
451.PP
452just beeps, because `fo' could expand to `fod' or `foo', but if we type
453another `o',
454.IP "" 4
455> rm foo[tab]
456.br
457> rm foo
458.PP
459the completion completes on `foo', even though `food' and `foonly'
460also match.
461\fBautoexpand\fR can be set to run the \fIexpand-history\fR editor command
462before each completion attempt, \fBautocorrect\fR can be set to
463spelling-correct the word to be completed (see \fBSpelling correction\fR)
464before each completion attempt and \fBcorrect\fR can be set to complete
465commands automatically after one hits `return'.
466\fBmatchbeep\fR can be set to make completion beep or not beep in a variety
467of situations, and \fBnobeep\fR can be set to never beep at all.
468\fBnostat\fR can be set to a list of directories and/or patterns that
469match directories to prevent the completion mechanism from \fIstat\fR(2)ing
470those directories.
471\fBlistmax\fR and \fBlistmaxrows\fR can be set to limit the number of items
472and rows (respectively) that are listed without asking first.
473\fBrecognize_only_executables\fR can be set to make the shell list only
474executables when listing commands, but it is quite slow.
475.PP
476Finally, the \fIcomplete\fR builtin command can be used to tell the shell how
477to complete words other than filenames, commands and variables.
478Completion and listing do not work on glob-patterns (see \fBFilename substitution\fR),
479but the \fIlist-glob\fR and \fIexpand-glob\fR editor commands perform
480equivalent functions for glob-patterns.
481.SS "Spelling correction (+)"
482The shell can sometimes correct the spelling of filenames, commands and variable names
483as well as completing and listing them.
484.PP
485Individual words can be spelling-corrected with the \fIspell-word\fR
486editor command (usually bound to M-s and M-S)
487and the entire input buffer with \fIspell-line\fR (usually bound to M-$).
488The \fBcorrect\fR shell variable can be set to `cmd' to correct the
489command name or `all' to correct the entire line each time return is typed,
490and \fBautocorrect\fR can be set to correct the word to be completed
491before each completion attempt.
492.PP
493When spelling correction is invoked in any of these ways and
494the shell thinks that any part of the command line is misspelled,
495it prompts with the corrected line:
496.IP "" 4
497> set correct = cmd
498.br
499> lz /usr/bin
500.br
501CORRECT>ls /usr/bin (y|n|e|a)?
502.PP
503One can answer `y' or space to execute the corrected line,
504`e' to leave the uncorrected command in the input buffer,
505`a' to abort the command as if `^C' had been hit, and
506anything else to execute the original line unchanged.
507.PP
508Spelling correction recognizes user-defined completions (see the
509\fIcomplete\fR builtin command). If an input word in a position for
510which a completion is defined resembles a word in the completion list,
511spelling correction registers a misspelling and suggests the latter
512word as a correction. However, if the input word does not match any of
513the possible completions for that position, spelling correction does
514not register a misspelling.
515.PP
516Like completion, spelling correction works anywhere in the line,
517pushing the rest of the line to the right and possibly leaving
518extra characters to the right of the cursor.
519.PP
520Beware: spelling correction is not guaranteed to work the way one intends,
521and is provided mostly as an experimental feature.
522Suggestions and improvements are welcome.
523.SS "Editor commands (+)"
524`bindkey' lists key bindings and `bindkey \-l' lists and briefly describes
525editor commands.
526Only new or especially interesting editor commands are described here.
527See \fIemacs\fR(1) and \fIvi\fR(1) for descriptions of each editor's
528key bindings.
529.PP
530The character or characters to which each command is bound by default is
531given in parentheses. `^\fIcharacter\fR' means a control character and
532`M-\fIcharacter\fR' a meta character, typed as escape-\fIcharacter\fR
533on terminals without a meta key. Case counts, but commands that are bound
534to letters by default are bound to both lower- and uppercase letters for
535convenience.
536.TP 8
537.B complete-word \fR(tab)
538Completes a word as described under \fBCompletion and listing\fR.
539.TP 8
540.B complete-word-back \fR(not bound)
541Like \fIcomplete-word-fwd\fR, but steps up from the end of the list.
542.TP 8
543.B complete-word-fwd \fR(not bound)
544Replaces the current word with the first word in the list of possible
545completions. May be repeated to step down through the list.
546At the end of the list, beeps and reverts to the incomplete word.
547.TP 8
548.B complete-word-raw \fR(^X-tab)
549Like \fIcomplete-word\fR, but ignores user-defined completions.
550.TP 8
551.B copy-prev-word \fR(M-^_)
552Copies the previous word in the current line into the input buffer.
553See also \fIinsert-last-word\fR.
554.TP 8
555.B dabbrev-expand \fR(M-/)
556Expands the current word to the most recent preceding one for which
557the current is a leading substring, wrapping around the history list
558(once) if necessary.
559Repeating \fIdabbrev-expand\fR without any intervening typing
560changes to the next previous word etc., skipping identical matches
561much like \fIhistory-search-backward\fR does.
562.TP 8
563.B delete-char \fR(not bound)
564Deletes the character under the cursor.
565See also \fIdelete-char-or-list-or-eof\fR.
566.TP 8
567.B delete-char-or-eof \fR(not bound)
568Does \fIdelete-char\fR if there is a character under the cursor
569or \fIend-of-file\fR on an empty line.
570See also \fIdelete-char-or-list-or-eof\fR.
571.TP 8
572.B delete-char-or-list \fR(not bound)
573Does \fIdelete-char\fR if there is a character under the cursor
574or \fIlist-choices\fR at the end of the line.
575See also \fIdelete-char-or-list-or-eof\fR.
576.TP 8
577.B delete-char-or-list-or-eof \fR(^D)
578Does \fIdelete-char\fR if there is a character under the cursor,
579\fIlist-choices\fR at the end of the line
580or \fIend-of-file\fR on an empty line.
581See also those three commands, each of which does only a single action, and
582\fIdelete-char-or-eof\fR, \fIdelete-char-or-list\fR and \fIlist-or-eof\fR,
583each of which does a different two out of the three.
584.TP 8
585.B down-history \fR(down-arrow, ^N)
586Like \fIup-history\fR, but steps down, stopping at the original input line.
587.TP 8
588.B end-of-file \fR(not bound)
589Signals an end of file, causing the shell to exit unless the \fBignoreeof\fR
590shell variable (q.v.) is set to prevent this.
591See also \fIdelete-char-or-list-or-eof\fR.
592.TP 8
593.B expand-history \fR(M-space)
594Expands history substitutions in the current word.
595See \fBHistory substitution\fR.
596See also \fImagic-space\fR, \fItoggle-literal-history\fR and
597the \fBautoexpand\fR shell variable.
598.TP 8
599.B expand-glob \fR(^X-*)
600Expands the glob-pattern to the left of the cursor.
601See \fBFilename substitution\fR.
602.TP 8
603.B expand-line \fR(not bound)
604Like \fIexpand-history\fR, but
605expands history substitutions in each word in the input buffer,
606.TP 8
607.B expand-variables \fR(^X-$)
608Expands the variable to the left of the cursor.
609See \fBVariable substitution\fR.
610.TP 8
611.B history-search-backward \fR(M-p, M-P)
612Searches backwards through the history list for a command beginning with
613the current contents of the input buffer up to the cursor and copies it
614into the input buffer.
615The search string may be a glob-pattern (see \fBFilename substitution\fR)
616containing `*', `?', `[]' or `{}'.
617\fIup-history\fR and \fIdown-history\fR will proceed from the
618appropriate point in the history list.
619Emacs mode only.
620See also \fIhistory-search-forward\fR and \fIi-search-back\fR.
621.TP 8
622.B history-search-forward \fR(M-n, M-N)
623Like \fIhistory-search-backward\fR, but searches forward.
624.TP 8
625.B i-search-back \fR(not bound)
626Searches backward like \fIhistory-search-backward\fR, copies the first match
627into the input buffer with the cursor positioned at the end of the pattern,
628and prompts with `bck: ' and the first match. Additional characters may be
629typed to extend the search, \fIi-search-back\fR may be typed to continue
630searching with the same pattern, wrapping around the history list if
631necessary, (\fIi-search-back\fR must be bound to a
632single character for this to work) or one of the following special characters
633may be typed:
634.PP
635.RS +8
636.RS +4
637.PD 0
638.TP 8
639^W
640Appends the rest of the word under the cursor to the search pattern.
641.TP 8
642delete (or any character bound to \fIbackward-delete-char\fR)
643Undoes the effect of the last character typed and deletes a character
644from the search pattern if appropriate.
645.TP 8
646^G
647If the previous search was successful, aborts the entire search.
648If not, goes back to the last successful search.
649.TP 8
650escape
651Ends the search, leaving the current line in the input buffer.
652.RE
653.PD
654.PP
655Any other character not bound to \fIself-insert-command\fR terminates the
656search, leaving the current line in the input buffer, and
657is then interpreted as normal input. In particular, a carriage return
658causes the current line to be executed.
659Emacs mode only.
660See also \fIi-search-fwd\fR and \fIhistory-search-backward\fR.
661.RE
662.TP 8
663.B i-search-fwd \fR(not bound)
664Like \fIi-search-back\fR, but searches forward.
665.TP 8
666.B insert-last-word \fR(M-_)
667Inserts the last word of the previous input line (`!$') into the input buffer.
668See also \fIcopy-prev-word\fR.
669.TP 8
670.B list-choices \fR(M-^D)
671Lists completion possibilities as described under \fBCompletion and listing\fR.
672See also \fIdelete-char-or-list-or-eof\fR and \fIlist-choices-raw\fR.
673.TP 8
674.B list-choices-raw \fR(^X-^D)
675Like \fIlist-choices\fR, but ignores user-defined completions.
676.TP 8
677.B list-glob \fR(^X-g, ^X-G)
678Lists (via the \fIls\-F\fR builtin) matches to the glob-pattern
679(see \fBFilename substitution\fR) to the left of the cursor.
680.TP 8
681.B list-or-eof \fR(not bound)
682Does \fIlist-choices\fR
683or \fIend-of-file\fR on an empty line.
684See also \fIdelete-char-or-list-or-eof\fR.
685.TP 8
686.B magic-space \fR(not bound)
687Expands history substitutions in the current line,
688like \fIexpand-history\fR, and appends a space.
689\fImagic-space\fR is designed to be bound to the space bar,
690but is not bound by default.
691.TP 8
692.B normalize-command \fR(^X-?)
693Searches for the current word in PATH and, if it is found, replaces it with
694the full path to the executable. Special characters are quoted. Aliases are
695expanded and quoted but commands within aliases are not. This command is
696useful with commands that take commands as arguments, e.g., `dbx' and `sh \-x'.
697.TP 8
698.B normalize-path \fR(^X-n, ^X-N)
699Expands the current word as described under the `expand' setting
700of the \fBsymlinks\fR shell variable.
701.TP 8
702.B overwrite-mode \fR(unbound)
703Toggles between input and overwrite modes.
704.TP 8
705.B run-fg-editor \fR(M-^Z)
706Saves the current input line and
707looks for a stopped job with a name equal to the last component of the
708file name part of the \fBEDITOR\fR or \fBVISUAL\fR environment variables,
709or, if neither is set, `ed' or `vi'.
710If such a job is found, it is restarted as if `fg %\fIjob\fR' had been
711typed. This is used to toggle back and forth between an editor and
712the shell easily. Some people bind this command to `^Z' so they
713can do this even more easily.
714.TP
715.B run-help \fR(M-h, M-H)
716Searches for documentation on the current command, using the same notion of
717`current command' as the completion routines, and prints it. There is no way
718to use a pager; \fIrun-help\fR is designed for short help files.
719If the special alias \fBhelpcommand\fR is defined, it is run with the
720command name as a sole argument. Else,
721documentation should be in a file named \fIcommand\fR.help, \fIcommand\fR.1,
722\fIcommand\fR.6, \fIcommand\fR.8 or \fIcommand\fR, which should be in one
723of the directories listed in the \fBHPATH\fR environment variable.
724If there is more than one help file only the first is printed.
725.TP 8
726.B self-insert-command \fR(text characters)
727In insert mode (the default), inserts the typed character into the input line after the character under the cursor.
728In overwrite mode, replaces the character under the cursor with the typed character.
729The input mode is normally preserved between lines, but the
730\fBinputmode\fR shell variable can be set to `insert' or `overwrite' to put the
731editor in that mode at the beginning of each line.
732See also \fIoverwrite-mode\fR.
733.TP 8
734.B sequence-lead-in \fR(arrow prefix, meta prefix, ^X)
735Indicates that the following characters are part of a
736multi-key sequence. Binding a command to a multi-key sequence really creates
737two bindings: the first character to \fIsequence-lead-in\fR and the
738whole sequence to the command. All sequences beginning with a character
739bound to \fIsequence-lead-in\fR are effectively bound to \fIundefined-key\fR
740unless bound to another command.
741.TP 8
742.B spell-line \fR(M-$)
743Attempts to correct the spelling of each word in the input buffer, like
744\fIspell-word\fR, but ignores words whose first character is one of
745`\-', `!', `^' or `%', or which contain `\\', `*' or `?', to avoid problems
746with switches, substitutions and the like.
747See \fBSpelling correction\fR.
748.TP 8
749.B spell-word \fR(M-s, M-S)
750Attempts to correct the spelling of the current word as described
751under \fBSpelling correction\fR.
752Checks each component of a word which appears to be a pathname.
753.TP 8
754.B toggle-literal-history \fR(M-r, M-R)
755Expands or `unexpands' history substitutions in the input buffer.
756See also \fIexpand-history\fR and the \fBautoexpand\fR shell variable.
757.TP 8
758.B undefined-key \fR(any unbound key)
759Beeps.
760.TP 8
761.B up-history \fR(up-arrow, ^P)
762Copies the previous entry in the history list into the input buffer.
763If \fBhistlit\fR is set, uses the literal form of the entry.
764May be repeated to step up through the history list, stopping at the top.
765.TP 8
766.B vi-search-back \fR(?)
767Prompts with `?' for a search string (which may be a glob-pattern, as with
768\fIhistory-search-backward\fR), searches for it and copies it into the
769input buffer. The bell rings if no match is found.
770Hitting return ends the search and leaves the last match in the input
771buffer.
772Hitting escape ends the search and executes the match.
773\fIvi\fR mode only.
774.TP 8
775.B vi-search-fwd \fR(/)
776Like \fIvi-search-back\fR, but searches forward.
777.TP 8
778.B which-command \fR(M-?)
779Does a \fIwhich\fR (see the description of the builtin command) on the
780first word of the input buffer.
781.SS "Lexical structure"
782The shell splits input lines into words at blanks and tabs. The special
783characters `&', `|', `;', `<', `>', `(', and `)' and the doubled characters
784`&&', `||', `<<' and `>>' are always separate words, whether or not they are
785surrounded by whitespace.
786.PP
787When the shell's input is not a terminal, the character `#' is taken to begin a
788comment. Each `#' and the rest of the input line on which it appears is
789discarded before further parsing.
790.PP
791A special character (including a blank or tab) may be prevented from having
792its special meaning, and possibly made part of another word, by preceding it
793with a backslash (`\\') or enclosing it in single (`''), double (`"') or
794backward (``') quotes. When not otherwise quoted a newline preceded by a `\\'
795is equivalent to a blank, but inside quotes this sequence results in a
796newline.
797.PP
798Furthermore, all \fBSubstitutions\fR (see below) except \fBHistory substitution\fR
799can be prevented by enclosing the strings (or parts of strings)
800in which they appear with single quotes or by quoting the crucial character(s)
801(e.g., `$' or ``' for \fBVariable substitution\fR or \fBCommand substitution\fR respectively)
802with `\\'. (\fBAlias substitution\fR is no exception: quoting in any way any
803character of a word for which an \fIalias\fR has been defined prevents
804substitution of the alias. The usual way of quoting an alias is to precede it
805with a backslash.) \fBHistory substitution\fR is prevented by
806backslashes but not by single quotes. Strings quoted with double or backward
807quotes undergo \fBVariable substitution\fR and \fBCommand substitution\fR, but other
808substitutions are prevented.
809.PP
810Text inside single or double quotes becomes a single word (or part of one).
811Metacharacters in these strings, including blanks and tabs, do not form
812separate words. Only in one special case (see \fBCommand substitution\fR
813below) can a double-quoted string yield parts of more than one word;
814single-quoted strings never do. Backward quotes are special: they signal
815\fBCommand substitution\fR (q.v.), which may result in more than one word.
816.PP
817Quoting complex strings, particularly strings which themselves contain quoting
818characters, can be confusing. Remember that quotes need not be used as they are
819in human writing! It may be easier to quote not an entire string, but only
820those parts of the string which need quoting, using different types of quoting
821to do so if appropriate.
822.PP
823The \fBbackslash_quote\fR shell variable (q.v.) can be set to make backslashes
824always quote `\\', `'', and `"'. (+) This may make complex quoting tasks
825easier, but it can cause syntax errors in \fIcsh\fR(1) scripts.
826.SS Substitutions
827We now describe the various transformations the shell performs on the input in
828the order in which they occur. We note in passing the data structures involved
829and the commands and variables which affect them. Remember that substitutions
830can be prevented by quoting as described under \fBLexical structure\fR.
831.SS "History substitution"
832Each command, or ``event'', input from the terminal is saved in the history
833list. The previous command is always saved, and the \fBhistory\fR shell
834variable can be set to a number to save that many commands. The \fBhistdup\fR
835shell variable can be set to not save duplicate events or consecutive duplicate
836events.
837.PP
838Saved commands are numbered sequentially from 1 and stamped with the time.
839It is not usually necessary to use event numbers, but the current event number
840can be made part of the prompt by placing an `!' in the \fBprompt\fR shell variable.
841.PP
842The shell actually saves history in expanded and literal (unexpanded) forms.
843If the \fBhistlit\fR shell variable is set, commands that display and store
844history use the literal form.
845.PP
846The \fIhistory\fR builtin command can print, store in a file, restore
847and clear the history list at any time,
848and the \fBsavehist\fR and \fBhistfile\fR shell variables can be can be set to
849store the history list automatically on logout and restore it on login.
850.PP
851History substitutions introduce words from the history list into the input
852stream, making it easy to repeat commands, repeat arguments of a previous
853command in the current command, or fix spelling mistakes in the previous
854command with little typing and a high degree of confidence.
855.PP
856History substitutions begin with the character `!'. They may begin anywhere in
857the input stream, but they do not nest. The `!' may be preceded by a `\\' to
858prevent its special meaning; for convenience, a `!' is passed unchanged when it
859is followed by a blank, tab, newline, `=' or `('. History substitutions also
860occur when an input line begins with `^'. This special abbreviation will be
861described later. The characters used to signal history substitution (`!' and
862`^') can be changed by setting the \fBhistchars\fR shell variable. Any input
863line which contains a history substitution is printed before it is executed.
864.PP
865A history substitution may have an ``event specification'', which indicates
866the event from which words are to be taken, a ``word designator'',
867which selects particular words from the chosen event, and/or a ``modifier'',
868which manipulates the selected words.
869.PP
870An event specification can be
871.PP
872.PD 0
873.RS +4
874.TP 8
875.I n
876A number, referring to a particular event
877.TP 8
878\-\fIn\fR
879An offset, referring to the event \fIn\fR before the current event
880.TP 8
881#
882The current event.
883This should be used carefully in \fIcsh\fR(1), where there is no check for
884recursion. \fItcsh\fR allows 10 levels of recursion. (+)
885.TP 8
886!
887The previous event (equivalent to `\-1')
888.TP 8
889.I s
890The most recent event whose first word begins with the string \fIs\fR
891.TP 8
892?\fIs\fR?
893The most recent event which contains the string \fIs\fR.
894The second `?' can be omitted if it is immediately followed by a newline.
895.RE
896.PD
897.PP
898For example, consider this bit of someone's history list:
899.IP "" 4
900\ 9 8:30 nroff \-man wumpus.man
901.br
90210 8:31 cp wumpus.man wumpus.man.old
903.br
90411 8:36 vi wumpus.man
905.br
90612 8:37 diff wumpus.man.old wumpus.man
907.PP
908The commands are shown with their event numbers and time stamps.
909The current event, which we haven't typed in yet, is event 13.
910`!11' and `!\-2' refer to event 11.
911`!!' refers to the previous event, 12. `!!' can be abbreviated `!' if it is
912followed by `:' (`:' is described below).
913`!n' refers to event 9, which begins with `n'.
914`!?old?' also refers to event 12, which contains `old'.
915Without word designators or modifiers history references simply expand to the
916entire event, so we might type `!cp' to redo the copy command or `!!|more'
917if the `diff' output scrolled off the top of the screen.
918.PP
919History references may be insulated from the surrounding text with braces if
920necessary. For example, `!vdoc' would look for a command beginning with
921`vdoc', and, in this example, not find one, but `!{v}doc' would expand
922unambiguously to `vi wumpus.mandoc'.
923Even in braces, history substitutions do not nest.
924.PP
925(+) While \fIcsh\fR(1) expands, for example, `!3d' to event 3 with the
926letter `d' appended to it, \fItcsh\fR expands it to the last event beginning
927with `3d'; only completely numeric arguments are treated as event numbers.
928This makes it possible to recall events beginning with numbers.
929To expand `!3d' as in \fIcsh\fR(1) say `!\\3d'.
930.PP
931To select words from an event we can follow the event specification by a `:'
932and a designator for the desired words. The words of an input line are
933numbered from 0, the first (usually command) word being 0, the second word
934(first argument) being 1, etc. The basic word designators are:
935.PP
936.PD 0
937.RS +4
938.TP 8
9390
940The first (command) word
941.TP 8
942.I n
943The \fIn\fRth argument
944.TP 8
945^
946The first argument, equivalent to `1'
947.TP 8
948$
949The last argument
950.TP 8
951%
952The word matched by an ?\fIs\fR? search
953.TP 8
954.I x\-y
955A range of words
956.TP 8
957.I \-y
958Equivalent to \fI`0\-y'\fR
959.TP 8
960*
961Equivalent to `^\-$', but returns nothing if the event contains only 1 word
962.TP 8
963.I x*
964Equivalent to \fI`x\-$'\fR
965.TP 8
966.I x\-
967Equivalent to \fI`x*'\fR, but omitting the last word (`$')
968.PD
969.RE
970.PP
971Selected words are inserted into the command line separated by single blanks.
972For example, the `diff' command in the previous example might have been
973typed as `diff !!:1.old !!:1' (using `:1' to select the first argument
974from the previous event) or `diff !\-2:2 !\-2:1' to select and swap the
975arguments from the `cp' command. If we didn't care about the order of the
976`diff' we might have said `diff !\-2:1\-2' or simply `diff !\-2:*'.
977The `cp' command might have been written `cp wumpus.man !#:1.old', using `#'
978to refer to the current event.
979`!n:\- hurkle.man' would reuse the first two words from the `nroff' command
980to say `nroff \-man hurkle.man'.
981.PP
982The `:' separating the event specification from the word designator can be
983omitted if the argument selector begins with a `^', `$', `*', `%' or `\-'.
984For example, our `diff' command might have been `diff !!^.old !!^' or,
985equivalently, `diff !!$.old !!$'. However, if `!!' is abbreviated `!',
986an argument selector beginning with `\-' will be interpreted as an event
987specification.
988.PP
989A history reference may have a word designator but no event specification.
990It then references the previous command.
991.ig \" Not true, but we thought it was for a long time ...
992, unless a previous history reference
993occurred on the same line in which case this form repeats the previous
994reference. Thus `!?foo?^ !$' gives the first and last arguments from the
995command matching `?foo?'.
996..
997Continuing our `diff' example, we could have said simply `diff
998!^.old !^' or, to get the arguments in the opposite order, just `diff !*'.
999.PP
1000The word or words in a history reference can be edited, or ``modified'',
1001by following it with one or more modifiers, each preceded by a `:':
1002.PP
1003.PD 0
1004.RS +4
1005.TP 8
1006h
1007Remove a trailing pathname component, leaving the head.
1008.TP 8
1009t
1010Remove all leading pathname components, leaving the tail.
1011.TP 8
1012r
1013Remove a filename extension `.xxx', leaving the root name.
1014.TP 8
1015e
1016Remove all but the extension.
1017.TP 8
1018u
1019Uppercase the first lowercase letter.
1020.TP 8
1021l
1022Lowercase the first uppercase letter.
1023.TP 8
1024s\fI/l/r/\fR
1025Substitute \fIl\fR for \fIr\fR.
1026\fIl\fR is simply a string like \fIr\fR, not a regular expression as in
1027the eponymous \fIed\fR(1) command.
1028Any character may be used as the delimiter in place of `/';
1029a `\\' can be used to quote the delimiter inside \fIl\fR and \fIr\fR.
1030The character `&' in the \fIr\fR is replaced by \fIl\fR; `\\' also quotes `&'.
1031If \fIl\fR is empty (``''), the \fIl\fR from a previous substitution or the
1032\fIs\fR from a previous `?\fIs\fR?' event specification is used.
1033The trailing delimiter may be omitted if it is immediately followed by a newline.
1034.TP 8
1035&
1036Repeat the previous substitution.
1037.TP 8
1038g
1039Apply the following modifier once to each word.
1040.TP 8
1041a (+)
1042Apply the following modifier as many times as possible to a single word.
1043`a' and `g' can be used together to apply a modifier globally.
1044In the current implementation, using the `a' and `s' modifiers together can
1045lead to an infinite loop. For example, `:as/f/ff/' will never terminate.
1046This behavior might change in the future.
1047.TP 8
1048p
1049Print the new command line but do not execute it.
1050.TP 8
1051q
1052Quote the substituted words, preventing further substitutions.
1053.TP 8
1054x
1055Like q, but break into words at blanks, tabs and newlines.
1056.PD
1057.RE
1058.PP
1059Modifiers are applied to only the first modifiable word (unless `g' is used).
1060It is an error for no word to be modifiable.
1061.PP
1062For example, the `diff' command might have been written as `diff wumpus.man.old
1063!#^:r', using `:r' to remove `.old' from the first argument on the same line
1064(`!#^'). We could say `echo hello out there', then `echo !*:u' to capitalize
1065`hello', `echo !*:au' to say it out loud, or `echo !*:agu' to really shout.
1066We might follow `mail \-s "I forgot my password" rot' with `!:s/rot/root' to
1067correct the spelling of `root' (but see \fBSpelling correction\fR for a
1068different approach).
1069.PP
1070There is a special abbreviation for substitutions.
1071`^', when it is the first character on an input line, is equivalent to `!:s^'.
1072Thus we might have said `^rot^root' to make the spelling correction in the
1073previous example.
1074This is the only history substitution which does not explicitly begin with `!'.
1075.PP
1076(+) In \fIcsh\fR as such, only one modifier may be applied to each history
1077or variable expansion. In \fItcsh\fR, more than one may be used, for example
1078.IP "" 4
1079% mv wumpus.man /usr/man/man1/wumpus.1
1080.br
1081% man !$:t:r
1082.br
1083man wumpus
1084.PP
1085In \fIcsh\fR, the result would be `wumpus.1:r'. A substitution followed by a
1086colon may need to be insulated from it with braces:
1087.IP "" 4
1088> mv a.out /usr/games/wumpus
1089.br
1090> setenv PATH !$:h:$PATH
1091.br
1092Bad ! modifier: $.
1093.br
1094> setenv PATH !{\-2$:h}:$PATH
1095.br
1096setenv PATH /usr/games:/bin:/usr/bin:.
1097.PP
1098The first attempt would succeed in \fIcsh\fR but fails in \fItcsh\fR,
1099because \fItcsh\fR expects another modifier after the second colon
1100rather than `$'.
1101.PP
1102Finally, history can be accessed through the editor as well as through
1103the substitutions just described.
1104The \fIup-\fR and \fIdown-history\fR, \fIhistory-search-backward\fR and
1105\fI-forward\fR, \fIi-search-back\fR and \fI-fwd\fR,
1106\fIvi-search-back\fR and \fI-fwd\fR, \fIcopy-prev-word\fR
1107and \fIinsert-last-word\fR editor commands search for
1108events in the history list and copy them into the input buffer.
1109The \fItoggle-literal-history\fR editor command switches between the
1110expanded and literal forms of history lines in the input buffer.
1111\fIexpand-history\fR and \fIexpand-line\fR expand history substitutions
1112in the current word and in the entire input buffer respectively.
1113.SS "Alias substitution"
1114The shell maintains a list of aliases which can be set, unset and printed by
1115the \fIalias\fR and \fIunalias\fR commands. After a command line is parsed
1116into simple commands (see \fBCommands\fR) the first word of each command,
1117left-to-right, is checked to see if it has an alias. If so, the first word is
1118replaced by the alias. If the alias contains a history reference, it undergoes
1119\fBHistory substitution\fR (q.v.) as though the original command were the
1120previous input line. If the alias does not contain a history reference, the
1121argument list is left untouched.
1122.PP
1123Thus if the alias for `ls' were `ls \-l' the command `ls /usr' would become `ls
1124\-l /usr', the argument list here being undisturbed. If the alias for `lookup'
1125were `grep !^ /etc/passwd' then `lookup bill' would become `grep bill
1126/etc/passwd'. Aliases can be used to introduce parser metasyntax. For
1127example, `alias print 'pr \e!* | lpr'' defines a ``command'' (`print') which
1128\fIpr\fR(1)s its arguments to the line printer.
1129.PP
1130Alias substitution is repeated until the first word of the command has no
1131alias. If an alias substitution does not change the first word (as in the
1132previous example) it is flagged to prevent a loop. Other loops are detected and
1133cause an error.
1134.PP
1135Some aliases are referred to by the shell; see \fBSpecial aliases\fR.
1136.SS "Variable substitution"
1137The shell maintains a list of variables, each of which has as value a list of
1138zero or more words.
1139The values of shell variables can be displayed and changed with the
1140\fIset\fR and \fIunset\fR commands.
1141The system maintains its own list of ``environment'' variables.
1142These can be displayed and changed with \fIprintenv\fR, \fIsetenv\fR and
1143\fIunsetenv\fR.
1144.PP
1145(+) Variables may be made read-only with `set \-r' (q.v.)
1146Read-only variables may not be modified or unset;
1147attempting to do so will cause an error.
1148Once made read-only, a variable cannot be made writable,
1149so `set \-r' should be used with caution.
1150Environment variables cannot be made read-only.
1151.PP
1152Some variables are set by the shell or referred to by it.
1153For instance, the \fBargv\fR variable is an image of the shell's argument
1154list, and words of this variable's value are referred to in special ways.
1155Some of the variables referred to by the shell are toggles;
1156the shell does not care what their value is, only whether they are set or not.
1157For instance, the \fBverbose\fR variable is a toggle which causes command
1158input to be echoed. The \fB\-v\fR command line option sets this variable.
1159\fBSpecial shell variables\fR lists all variables which are referred to by the shell.
1160.PP
1161Other operations treat variables numerically. The `@' command permits numeric
1162calculations to be performed and the result assigned to a variable. Variable
1163values are, however, always represented as (zero or more) strings. For the
1164purposes of numeric operations, the null string is considered to be zero, and
1165the second and subsequent words of multi-word values are ignored.
1166.PP
1167After the input line is aliased and parsed, and before each command is
1168executed, variable substitution is performed keyed by `$' characters. This
1169expansion can be prevented by preceding the `$' with a `\e' except within `"'s
1170where it \fIalways\fR occurs, and within `''s where it \fInever\fR occurs.
1171Strings quoted by ``' are interpreted later (see \fBCommand substitution\fR
1172below) so `$' substitution does not occur there until later,
1173if at all. A `$' is passed unchanged if followed by a blank, tab, or
1174end-of-line.
1175.PP
1176Input/output redirections are recognized before variable expansion, and are
1177variable expanded separately. Otherwise, the command name and entire argument
1178list are expanded together. It is thus possible for the first (command) word
1179(to this point) to generate more than one word, the first of which becomes the
1180command name, and the rest of which become arguments.
1181.PP
1182Unless enclosed in `"' or given the `:q' modifier the results of variable
1183substitution may eventually be command and filename substituted. Within `"', a
1184variable whose value consists of multiple words expands to a (portion of a)
1185single word, with the words of the variable's value separated by blanks. When
1186the `:q' modifier is applied to a substitution the variable will expand to
1187multiple words with each word separated by a blank and quoted to prevent later
1188command or filename substitution.
1189.PP
1190The following metasequences are provided for introducing variable values into
1191the shell input. Except as noted, it is an error to reference a variable which
1192is not set.
1193.PP
1194.PD 0
1195$\fIname\fR
1196.TP 8
1197${\fIname\fR}
1198Substitutes the words of the value of variable \fIname\fR, each separated
1199by a blank. Braces insulate \fIname\fR from following characters which would
1200otherwise be part of it. Shell variables have names consisting of up to 20
1201letters and digits starting with a letter. The underscore character is
1202considered a letter. If \fIname\fR is not a shell variable, but is set in the
1203environment, then that value is returned (but `:' modifiers and the other forms
1204given below are not available in this case).
1205.PP
1206$\fIname\fR[\fIselector\fR]
1207.TP 8
1208${\fIname\fR[\fIselector\fR]}
1209Substitutes only the selected words from the value of \fIname\fR.
1210The \fIselector\fR is subjected to `$' substitution and may consist of
1211a single number or two numbers separated by a `\-'.
1212The first word of a variable's value is numbered `1'.
1213If the first number of a range is omitted it defaults to `1'.
1214If the last member of a range is omitted it defaults to `$#\fIname\fR'.
1215The \fIselector\fR `*' selects all words.
1216It is not an error for a range to be empty if the
1217second argument is omitted or in range.
1218.TP 8
1219$0
1220Substitutes the name of the file from which command input
1221is being read. An error occurs if the name is not known.
1222.PP
1223$\fInumber\fR
1224.TP 8
1225${\fInumber\fR}
1226Equivalent to `$argv[\fInumber\fR]'.
1227.TP 8
1228$*
1229Equivalent to `$argv', which is equivalent to `$argv[*]'.
1230.PD
1231.PP
1232The `:' modifiers described under \fBHistory substitution\fR, except for `:p',
1233can be applied to the substitutions above. More than one may be used. (+)
1234Braces may be needed to insulate a variable substitution from a literal colon
1235just as with \fBHistory substitution\fR (q.v.); any modifiers must appear
1236within the braces.
1237.PP
1238The following substitutions can not be modified with `:' modifiers.
1239.PP
1240.PD 0
1241$?\fIname\fR
1242.TP 8
1243${?\fIname\fR}
1244Substitutes the string `1' if \fIname\fR is set, `0' if it is not.
1245.TP 8
1246$?0
1247Substitutes `1' if the current input filename is known, `0' if it is not.
1248Always `0' in interactive shells.
1249.PP
1250$#\fIname\fR
1251.TP 8
1252${#\fIname\fR}
1253Substitutes the number of words in \fIname\fR.
1254.TP 8
1255$#
1256Equivalent to `$#argv'. (+)
1257.PP
1258$%\fIname\fR
1259.TP 8
1260${%\fIname\fR}
1261Substitutes the number of characters in \fIname\fR. (+)
1262.PP
1263$%\fInumber\fR
1264.TP 8
1265${%\fInumber\fR}
1266Substitutes the number of characters in $argv[\fInumber\fR]. (+)
1267.TP 8
1268$?
1269Equivalent to `$status'. (+)
1270.TP 8
1271$$
1272Substitutes the (decimal) process number of the (parent) shell.
1273.TP 8
1274$!
1275Substitutes the (decimal) process number of the last
1276background process started by this shell. (+)
1277.TP 8
1278$_
1279Substitutes the command line of the last command executed. (+)
1280.TP 8
1281$<
1282Substitutes a line from the standard input, with no further interpretation
1283thereafter. It can be used to read from the keyboard in a shell script.
1284(+) While \fIcsh\fR always quotes $<, as if it were equivalent to `$<:q',
1285\fItcsh\fR does not. Furthermore, when \fItcsh\fR is waiting for a line to be
1286typed the user may type an interrupt to interrupt the sequence into
1287which the line is to be substituted, but \fIcsh\fR does not allow this.
1288.PD
1289.PP
1290The editor command \fIexpand-variables\fR, normally bound to `^X-$',
1291can be used to interactively expand individual variables.
1292.SS "Command, filename and directory stack substitution"
1293The remaining substitutions are applied selectively to the arguments of builtin
1294commands. This means that portions of expressions which are not evaluated are
1295not subjected to these expansions. For commands which are not internal to the
1296shell, the command name is substituted separately from the argument list. This
1297occurs very late, after input-output redirection is performed, and in a child
1298of the main shell.
1299.SS "Command substitution"
1300Command substitution is indicated by a command enclosed in ``'. The output
1301from such a command is broken into separate words at blanks, tabs and newlines,
1302and null words are discarded. The output is variable and command substituted
1303and put in place of the original string.
1304.PP
1305Command substitutions inside double
1306quotes (`"') retain blanks and tabs; only newlines force new words. The single
1307final newline does not force a new word in any case. It is thus possible for a
1308command substitution to yield only part of a word, even if the command outputs
1309a complete line.
1310.SS "Filename substitution"
1311If a word contains any of the characters `*', `?', `[' or `{' or begins with
1312the character `~' it is a candidate for filename substitution, also known as
1313``globbing''. This word is then regarded as a pattern (``glob-pattern''), and
1314replaced with an alphabetically sorted list of file names which match the
1315pattern.
1316.PP
1317In matching filenames, the character `.' at the beginning of a filename or
1318immediately following a `/', as well as the character `/' must be matched
1319explicitly. The character `*' matches any string of characters, including the
1320null string. The character `?' matches any single character. The sequence
1321`[...]' matches any one of the characters enclosed. Within `[...]', a pair of
1322characters separated by `\-' matches any character lexically between the two.
1323.PP
1324(+) Some glob-patterns can be negated:
1325The sequence `[^...]' matches any single character \fInot\fR specified by the
1326characters and/or ranges of characters in the braces.
1327.PP
1328An entire glob-pattern can also be negated with `^':
1329.IP "" 4
1330> echo *
1331.br
1332bang crash crunch ouch
1333.br
1334> echo ^cr*
1335.br
1336bang ouch
1337.PP
1338Glob-patterns which do not use `?', `*', or `[]' or which use `{}' or `~'
1339(below) are not negated correctly.
1340.PP
1341The metanotation `a{b,c,d}e' is a shorthand for `abe ace ade'.
1342Left-to-right order is preserved: `/usr/source/s1/{oldls,ls}.c' expands
1343to `/usr/source/s1/oldls.c /usr/source/s1/ls.c'. The results of matches are
1344sorted separately at a low level to preserve this order:
1345`../{memo,*box}' might expand to `../memo ../box ../mbox'.
1346(Note that `memo' was not sorted with the results of matching `*box'.)
1347It is not an error when this construct expands to files which do not exist,
1348but it is possible to get an error from a command to which the expanded list
1349is passed.
1350This construct may be nested.
1351As a special case the words `{', `}' and `{}' are passed undisturbed.
1352.PP
1353The character `~' at the beginning of a filename refers to home directories.
1354Standing alone, i.e., `~', it expands to the invoker's home directory as
1355reflected in the value of the \fBhome\fR shell variable. When followed by a
1356name consisting of letters, digits and `\-' characters the shell searches for a
1357user with that name and substitutes their home directory; thus `~ken' might
1358expand to `/usr/ken' and `~ken/chmach' to `/usr/ken/chmach'. If the character
1359`~' is followed by a character other than a letter or `/' or appears elsewhere
1360than at the beginning of a word, it is left undisturbed.
1361A command like `setenv MANPATH /usr/man:/usr/local/man:~/lib/man' does not,
1362therefore, do home directory substitution as one might hope.
1363.PP
1364It is an error for a glob-pattern containing `*', `?', `[' or `~', with or
1365without `^', not to match any files. However, only one pattern in a list of
1366glob-patterns must match a file (so that, e.g., `rm *.a *.c *.o' would fail
1367only if there were no files in the current directory ending in `.a', `.c', or
1368`.o'), and if the \fBnonomatch\fR shell variable is set a pattern (or list
1369of patterns) which matches nothing is left unchanged rather than causing
1370an error.
1371.PP
1372The \fBnoglob\fR shell variable can be set to prevent filename substitution,
1373and the \fIexpand-glob\fR editor command, normally bound to `^X-*', can be
1374used to interactively expand individual filename substitutions.
1375.SS "Directory stack substitution (+)"
1376The directory stack is a list of directories, numbered from zero, used by the
1377\fIpushd\fR, \fIpopd\fR and \fIdirs\fR builtin commands (q.v.).
1378\fIdirs\fR can print, store in a file, restore and clear the directory stack
1379at any time, and the \fBsavedirs\fR and \fBdirsfile\fR shell variables can be set to
1380store the directory stack automatically on logout and restore it on login.
1381The \fBdirstack\fR shell variable can be examined to see the directory stack and
1382set to put arbitrary directories into the directory stack.
1383.PP
1384The character `=' followed by one or more digits expands to an entry in
1385the directory stack. The special case `=\-' expands to the last directory in
1386the stack. For example,
1387.IP "" 4
1388> dirs \-v
1389.br
13900 /usr/bin
1391.br
13921 /usr/spool/uucp
1393.br
13942 /usr/accts/sys
1395.br
1396> echo =1
1397.br
1398/usr/spool/uucp
1399.br
1400> echo =0/calendar
1401.br
1402/usr/bin/calendar
1403.br
1404> echo =\-
1405.br
1406/usr/accts/sys
1407.PP
1408The \fBnoglob\fR and \fBnonomatch\fR shell variables and the \fIexpand-glob\fR
1409editor command apply to directory stack as well as filename substitutions.
1410.SS "Other substitutions (+)"
1411There are several more transformations involving filenames, not strictly
1412related to the above but mentioned here for completeness.
1413\fIAny\fR filename may be expanded to a full path when the
1414\fBsymlinks\fR variable (q.v.) is set to `expand'.
1415Quoting prevents this expansion, and
1416the \fInormalize-path\fR editor command does it on demand.
1417The \fInormalize-command\fR editor command expands commands in PATH into
1418full paths on demand.
1419Finally, \fIcd\fR and \fIpushd\fR interpret `\-' as the old working directory
1420(equivalent to the shell variable \fBowd\fR).
1421This is not a substitution at all, but an abbreviation recognized by only
1422those commands. Nonetheless, it too can be prevented by quoting.
1423.SS Commands
1424The next three sections describe how the shell executes commands and
1425deals with their input and output.
1426.SS Simple commands, pipelines and sequences
1427A simple command is a sequence of words, the first of which specifies the
1428command to be executed. A series of simple commands joined by `|' characters
1429forms a pipeline. The output of each command in a pipeline is connected to the
1430input of the next.
1431.PP
1432Simple commands and pipelines may be joined into sequences with `;', and will
1433be executed sequentially. Commands and pipelines can also be joined into
1434sequences with `||' or `&&', indicating, as in the C language, that the second
1435is to be executed only if the first fails or succeeds respectively.
1436.PP
1437A simple command, pipeline or sequence may be placed in parentheses, `()',
1438to form a simple command, which may in turn be a component of a pipeline or
1439sequence. A command, pipeline or sequence can be executed
1440without waiting for it to terminate by following it with an `&'.
1441.SS "Builtin and non-builtin command execution"
1442Builtin commands are executed within the shell. If any component of a
1443pipeline except the last is a builtin command, the pipeline is executed
1444in a subshell.
1445.PP
1446Parenthesized commands are always executed in a subshell.
1447.IP "" 4
1448(cd; pwd); pwd
1449.PP
1450thus prints the \fBhome\fR directory, leaving you where you were
1451(printing this after the home directory), while
1452.IP "" 4
1453cd; pwd
1454.PP
1455leaves you in the \fBhome\fR directory. Parenthesized commands are most often
1456used to prevent \fIcd\fR from affecting the current shell.
1457.PP
1458When a command to be executed is found not to be a builtin command the shell
1459attempts to execute the command via \fIexecve\fR(2). Each word in the variable
1460\fBpath\fR names a directory in which the shell will look for the
1461command. If it is given neither a \fB\-c\fR nor a \fB\-t\fR option, the shell
1462hashes the names in these directories into an internal table so that it will
1463try an \fIexecve\fR(2) in only a directory where there is a possibility that the
1464command resides there. This greatly speeds command location when a large
1465number of directories are present in the search path. If this mechanism has
1466been turned off (via \fIunhash\fR), if the shell was given a \fB\-c\fR or
1467\fB\-t\fR argument or in any case for each directory component of \fBpath\fR
1468which does not begin with a `/', the shell concatenates the current working
1469directory with the given command name to form a path name of a file which it
1470then attempts to execute.
1471.PP
1472If the file has execute permissions but is not an executable to the system
1473(i.e., it is neither an executable binary nor a script that specifies its
1474interpreter), then it is assumed to be a file containing shell commands and
1475a new shell is spawned to read it. The \fIshell\fR special alias may be set
1476to specify an interpreter other than the shell itself.
1477.PP
1478On systems which do not understand the `#!' script interpreter convention
1479the shell may be compiled to emulate it; see the \fBversion\fR shell
1480variable\fR. If so, the shell checks the first line of the file to
1481see if it is of the form `#!\fIinterpreter\fR \fIarg\fR ...'. If it is,
1482the shell starts \fIinterpreter\fR with the given \fIarg\fRs and feeds the
1483file to it on standard input.
1484.SS Input/output
1485The standard input and standard output of a command may be redirected with the
1486following syntax:
1487.PP
1488.PD 0
1489.TP 8
1490< \fIname
1491Open file \fIname\fR (which is first variable, command and filename
1492expanded) as the standard input.
1493.TP 8
1494<< \fIword
1495Read the shell input up to a line which is identical to \fIword\fR. \fIword\fR
1496is not subjected to variable, filename or command substitution, and each input
1497line is compared to \fIword\fR before any substitutions are done on this input
1498line. Unless a quoting `\e', `"', `' or ``' appears in \fIword\fR variable and
1499command substitution is performed on the intervening lines, allowing `\e' to
1500quote `$', `\e' and ``'. Commands which are substituted have all blanks, tabs,
1501and newlines preserved, except for the final newline which is dropped. The
1502resultant text is placed in an anonymous temporary file which is given to the
1503command as standard input.
1504.PP
1505> \fIname
1506.br
1507>! \fIname
1508.br
1509>& \fIname
1510.TP 8
1511>&! \fIname
1512The file \fIname\fR is used as standard output. If the file does not exist
1513then it is created; if the file exists, it is truncated, its previous contents
1514being lost.
1515.RS +8
1516.PD
1517.PP
1518If the shell variable \fBnoclobber\fR is set, then the file must not exist or be a
1519character special file (e.g., a terminal or `/dev/null') or an error results.
1520This helps prevent accidental destruction of files. In this case the `!' forms
1521can be used to suppress this check.
1522.PP
1523The forms involving `&' route the diagnostic output into the specified file as
1524well as the standard output. \fIname\fR is expanded in the same way as `<'
1525input filenames are.
1526.PD 0
1527.RE
1528.PP
1529>> \fIname
1530.br
1531>>& \fIname
1532.br
1533>>! \fIname
1534.TP 8
1535>>&! \fIname
1536Like `>', but appends output to the end of \fIname\fR.
1537If the shell variable \fBnoclobber\fR is set, then it is an error for
1538the file \fInot\fR to exist, unless one of the `!' forms is given.
1539.PD
1540.PP
1541A command receives the environment in which the shell was invoked as modified
1542by the input-output parameters and the presence of the command in a pipeline.
1543Thus, unlike some previous shells, commands run from a file of shell commands
1544have no access to the text of the commands by default; rather they receive the
1545original standard input of the shell. The `<<' mechanism should be used to
1546present inline data. This permits shell command scripts to function as
1547components of pipelines and allows the shell to block read its input. Note
1548that the default standard input for a command run detached is \fInot\fR
1549the empty file \fI/dev/null\fR, but the original standard input of the shell.
1550If this is a terminal and if the process attempts to read from the terminal,
1551then the process will block and the user will be notified (see \fBJobs\fR).
1552.PP
1553Diagnostic output may be directed through a pipe with the standard output.
1554Simply use the form `|&' rather than just `|'.
1555.PP
1556The shell cannot presently redirect diagnostic output without also redirecting
1557standard output, but `(\fIcommand\fR > \fIoutput-file\fR) >& \fIerror-file\fR'
1558is often an acceptable workaround. Either \fIoutput-file\fR or
1559\fIerror-file\fR may be `/dev/tty' to send output to the terminal.
1560.SS Features
1561Having described how the shell accepts, parses and executes
1562command lines, we now turn to a variety of its useful features.
1563.SS "Control flow"
1564The shell contains a number of commands which can be used to regulate the
1565flow of control in command files (shell scripts) and (in limited but
1566useful ways) from terminal input. These commands all operate by forcing the
1567shell to reread or skip in its input and, due to the implementation,
1568restrict the placement of some of the commands.
1569.PP
1570The \fIforeach\fR, \fIswitch\fR, and \fIwhile\fR statements, as well as the
1571\fIif-then-else\fR form of the \fIif\fR statement, require that the major
1572keywords appear in a single simple command on an input line as shown below.
1573.PP
1574If the shell's input is not seekable, the shell buffers up input whenever
1575a loop is being read and performs seeks in this internal buffer to
1576accomplish the rereading implied by the loop. (To the extent that this
1577allows, backward \fIgoto\fRs will succeed on non-seekable inputs.)
1578.SS Expressions
1579The \fIif\fR, \fIwhile\fR and \fIexit\fR builtin commands
1580use expressions with a common syntax. The expressions can include any
1581of the operators described in the next three sections. Note that the \fI@\fR
1582builtin command (q.v.) has its own separate syntax.
1583.SS "Logical, arithmetical and comparison operators"
1584These operators are similar to those of C and have the same precedence.
1585They include
1586.IP "" 4
1587|| && | ^ & == != =~ !~ <= >=
1588.br
1589< > << >> + \- * / % ! ~ ( )
1590.PP
1591Here the precedence increases to the right, `==' `!=' `=~' and `!~', `<='
1592`>=' `<' and `>', `<<' and `>>', `+' and `\-', `*' `/' and `%' being, in
1593groups, at the same level. The `==' `!=' `=~' and `!~' operators compare
1594their arguments as strings; all others operate on numbers. The operators
1595`=~' and `!~' are like `!=' and `==' except that the right hand side is a
1596glob-pattern (see \fBFilename substitution\fR) against which the left hand
1597operand is matched. This reduces the need for use of the \fIswitch\fR
1598builtin command in shell scripts when all that is really needed is
1599pattern matching.
1600.PP
1601Strings which begin with `0' are considered octal numbers. Null or
1602missing arguments are considered `0'. The results of all expressions are
1603strings, which represent decimal numbers. It is important to note that
1604no two components of an expression can appear in the same word; except
1605when adjacent to components of expressions which are syntactically
1606significant to the parser (`&' `|' `<' `>' `(' `)') they should be
1607surrounded by spaces.
1608.SS "Command exit status"
1609Commands can be executed in expressions and their exit status
1610returned by enclosing them in braces (`{}'). Remember that the braces should
1611be separated from the words of the command by spaces. Command executions
1612succeed, returning true, i.e., `1', if the command exits with status 0,
1613otherwise they fail, returning false, i.e., `0'. If more detailed status
1614information is required then the command should be executed outside of an
1615expression and the \fBstatus\fR shell variable examined.
1616.SS "File inquiry operators"
1617Some of these operators perform true/false tests on files and related
1618objects. They are of the form \fB\-\fIop file\fR, where \fIop\fR is one of
1619.PP
1620.PD 0
1621.RS +4
1622.TP 4
1623.B r
1624Read access
1625.TP 4
1626.B w
1627Write access
1628.TP 4
1629.B x
1630Execute access
1631.TP 4
1632.B X
1633Executable in the path or shell builtin, e.g., `\-X ls' and `\-X ls\-F' are
1634generally true, but `\-X /bin/ls' is not (+)
1635.TP 4
1636.B e
1637Existence
1638.TP 4
1639.B o
1640Ownership
1641.TP 4
1642.B z
1643Zero size
1644.TP 4
1645.B s
1646Non-zero size (+)
1647.TP 4
1648.B f
1649Plain file
1650.TP 4
1651.B d
1652Directory
1653.TP 4
1654.B l
1655Symbolic link (+) *
1656.TP 4
1657.B b
1658Block special file (+)
1659.TP 4
1660.B c
1661Character special file (+)
1662.TP 4
1663.B p
1664Named pipe (fifo) (+) *
1665.TP 4
1666.B S
1667Socket special file (+) *
1668.TP 4
1669.B u
1670Set-user-ID bit is set (+)
1671.TP 4
1672.B g
1673Set-group-ID bit is set (+)
1674.TP 4
1675.B k
1676Sticky bit is set (+)
1677.TP 4
1678.B t
1679\fIfile\fR (which must be a digit) is an open file descriptor
1680for a terminal device (+)
1681.TP 4
1682.B R
1683Has been migrated (convex only) (+)
1684.TP 4
1685.B L
1686Applies subsequent operators in a multiple-operator test to a symbolic link
1687rather than to the file to which the link points (+) *
1688.RE
1689.PD
1690.PP
1691\fIfile\fR is command and filename expanded and then tested to
1692see if it has the specified relationship to the real user. If \fIfile\fR
1693does not exist or is inaccessible or, for the operators indicated by `*',
1694if the specified file type does not exist on the current system,
1695then all enquiries return false, i.e., `0'.
1696.PP
1697These operators may be combined for conciseness: `\-\fIxy file\fR' is
1698equivalent to `\-\fIx file\fR && \-\fIy file\fR'. (+) For example, `\-fx' is true
1699(returns `1') for plain executable files, but not for directories.
1700.PP
1701\fBL\fR may be used in a multiple-operator test to apply subsequent operators
1702to a symbolic link rather than to the file to which the link points.
1703For example, `\-lLo' is true for links owned by the invoking user.
1704\fBLr\fR, \fBLw\fR and \fBLx\fR are always true for links and false for
1705non-links. \fBL\fR has a different meaning when it is the last operator
1706in a multiple-operator test; see below.
1707.PP
1708It is possible but not useful, and sometimes misleading, to combine operators
1709which expect \fIfile\fR to be a file with operators which do not,
1710(e.g., \fBX\fR and \fBt\fR). Following \fBL\fR with a non-file operator
1711can lead to particularly strange results.
1712.PP
1713Other operators return other information, i.e., not just `0' or `1'. (+)
1714They have the same format as before; \fIop\fR may be one of
1715.PP
1716.PD 0
1717.RS +4
1718.TP 8
1719.B A
1720Last file access time, as the number of seconds since the epoch
1721.TP 8
1722.B A:
1723Like \fBA\fR, but in timestamp format, e.g., `Fri May 14 16:36:10 1993'
1724.TP 8
1725.B M
1726Last file modification time
1727.TP 8
1728.B M:
1729Like \fBM\fR, but in timestamp format
1730.TP 8
1731.B C
1732Last inode modification time
1733.TP 8
1734.B C:
1735Like \fBC\fR, but in timestamp format
1736.TP 8
1737.B D
1738Device number
1739.TP 8
1740.B I
1741Inode number
1742.TP 8
1743.B F
1744Composite \fBf\fRile identifier, in the form \fIdevice\fR:\fIinode\fR
1745.TP 8
1746.B L
1747The name of the file pointed to by a symbolic link
1748.TP 8
1749.B N
1750Number of (hard) links
1751.TP 8
1752.B P
1753Permissions, in octal, without leading zero
1754.TP 8
1755.B P:
1756Like \fBP\fR, with leading zero
1757.TP 8
1758.B P\fImode
1759Equivalent to `\-P \fIfile\fR & \fImode\fR', e.g., `\-P22 \fIfile\fR' returns
1760`22' if \fIfile\fR is writable by group and other, `20' if by group only,
1761and `0' if by neither
1762.TP 8
1763.B P\fImode\fB:
1764Like \fBP\fImode\fB:\fR, with leading zero
1765.TP 8
1766.B U
1767Numeric userid
1768.TP 8
1769.B U:
1770Username, or the numeric userid if the username is unknown
1771.TP 8
1772.B G
1773Numeric groupid
1774.TP 8
1775.B G:
1776Groupname, or the numeric groupid if the groupname is unknown
1777.TP 8
1778.B Z
1779Size, in bytes
1780.RE
1781.PD
1782.PP
1783Only one of these operators may appear in a multiple-operator test, and it
1784must be the last. Note that \fBL\fR has a different meaning at the end of and
1785elsewhere in a multiple-operator test. Because `0' is a valid return value
1786for many of these operators, they do not return `0' when they fail: most
1787return `\-1', and \fBF\fR returns `:'.
1788.PP
1789If the shell is compiled with POSIX defined (see the \fBversion\fR shell
1790variable), the result of a file inquiry is based on the permission bits of
1791the file and not on the result of the \fIaccess\fR(2) system call.
1792For example, if one tests a file with \fB\-w\fR whose permissions would
1793ordinarily allow writing but which is on a file system mounted read-only,
1794the test will succeed in a POSIX shell but fail in a non-POSIX shell.
1795.PP
1796File inquiry operators can also be evaluated with the \fIfiletest\fR builtin
1797command (q.v.) (+).
1798.SS Jobs
1799The shell associates a \fIjob\fR with each pipeline. It keeps a table of
1800current jobs, printed by the \fIjobs\fR command, and assigns them small integer
1801numbers. When a job is started asynchronously with `&', the shell prints a
1802line which looks like
1803.IP "" 4
1804[1] 1234
1805.PP
1806indicating that the job which was started asynchronously was job number 1 and
1807had one (top-level) process, whose process id was 1234.
1808.PP
1809If you are running a job and wish to do something else you may hit the suspend
1810key (usually `^Z'),
1811which sends a STOP signal to the current job. The shell will then normally
1812indicate that the job has been `Suspended' and print another prompt.
1813If the \fBlistjobs\fR shell variable is set, all jobs will be listed
1814like the \fIjobs\fR builtin command; if it is set to `long' the listing will
1815be in long format, like `jobs \-l'.
1816You can then manipulate the state of the suspended job.
1817You can put it in the
1818``background'' with the \fIbg\fR command or run some other commands and
1819eventually bring the job back into the ``foreground'' with \fIfg\fR.
1820(See also the \fIrun-fg-editor\fR editor command.)
1821A `^Z' takes effect immediately and is like an interrupt
1822in that pending output and unread input are discarded when it is typed.
1823The \fIwait\fR builtin command causes the shell to wait for all background
1824jobs to complete.
1825.PP
1826The `^]' key sends a delayed suspend signal, which does not generate a STOP
1827signal until a program attempts to \fIread\fR(2) it, to the current job.
1828This can usefully be typed ahead when you have prepared some commands for a
1829job which you wish to stop after it has read them.
1830The `^Y' key performs this function in \fIcsh\fR(1); in \fItcsh\fR,
1831`^Y' is an editing command. (+)
1832.PP
1833A job being run in the background stops if it tries to read from the
1834terminal. Background jobs are normally allowed to produce output, but this can
1835be disabled by giving the command `stty tostop'. If you set this tty option,
1836then background jobs will stop when they try to produce output like they do
1837when they try to read input.
1838.PP
1839There are several ways to refer to jobs in the shell. The character `%'
1840introduces a job name. If you wish to refer to job number 1, you can name it
1841as `%1'. Just naming a job brings it to the foreground; thus `%1' is a synonym
1842for `fg %1', bringing job 1 back into the foreground. Similarly, saying `%1 &'
1843resumes job 1 in the background, just like `bg %1'. A job can also be named
1844by an unambiguous prefix of the string typed in to start it: `%ex' would
1845normally restart a suspended \fIex\fR(1) job, if there were only one suspended
1846job whose name began with the string `ex'. It is also possible to say
1847`%?\fIstring\fR' to specify a job whose text contains \fIstring\fR, if there
1848is only one such job.
1849.PP
1850The shell maintains a notion of the current and previous jobs. In output
1851pertaining to jobs, the current job is marked with a `+' and the previous job
1852with a `\-'. The abbreviations `%+', `%', and (by analogy with the syntax of
1853the \fIhistory\fR mechanism) `%%' all refer to the current job, and `%\-' refers
1854to the previous job.
1855.PP
1856The job control mechanism requires that the \fIstty\fR(1) option `new' be set
1857on some systems. It is an artifact from a `new' implementation of the tty
1858driver which allows generation of interrupt characters from the keyboard to
1859tell jobs to stop. See \fIstty\fR(1) and the \fIsetty\fR builtin command for
1860details on setting options in the new tty driver.
1861.SS "Status reporting"
1862The shell learns immediately whenever a process changes state. It normally
1863informs you whenever a job becomes blocked so that no further progress is
1864possible, but only right before it prints a prompt. This is done so that it
1865does not otherwise disturb your work. If, however, you set the shell variable
1866\fBnotify\fR, the shell will notify you immediately of changes of status in
1867background jobs. There is also a shell command \fInotify\fR which marks a
1868single process so that its status changes will be immediately reported. By
1869default \fInotify\fR marks the current process; simply say `notify' after
1870starting a background job to mark it.
1871.PP
1872When you try to leave the shell while jobs are stopped, you will be
1873warned that `You have stopped jobs.' You may use the \fIjobs\fR command to see
1874what they are. If you do this or immediately try to exit again, the shell will
1875not warn you a second time, and the suspended jobs will be terminated.
1876.SS "Automatic, periodic and timed events (+)"
1877There are various ways to run commands and take other actions automatically
1878at various times in the ``life cycle'' of the shell. They are summarized here,
1879and described in detail under the appropriate \fBBuiltin commands\fR,
1880\fBSpecial shell variables\fR and \fBSpecial aliases\fR.
1881.PP
1882The \fIsched\fR builtin command puts commands in a scheduled-event list,
1883to be executed by the shell at a given time.
1884.PP
| 214Commands like \fIstty\fR(1) and \fItset\fR(1),
215which need be run only once per login, usually go in one's \fI~/.login\fR file.
216Users who need to use the same set of files with both \fIcsh\fR(1) and
217\fItcsh\fR can have only a \fI~/.cshrc\fR which checks for the existence of the
218\fBtcsh\fR shell variable (q.v.) before using \fItcsh\fR-specific commands,
219or can have both a \fI~/.cshrc\fR and a \fI~/.tcshrc\fR which \fIsource\fRs
220(see the builtin command) \fI~/.cshrc\fR.
221The rest of this manual uses `\fI~/.tcshrc\fR' to mean `\fI~/.tcshrc\fR or,
222if \fI~/.tcshrc\fR is not found, \fI~/.cshrc\fR'.
223.PP
224In the normal case, the shell begins reading commands from the terminal,
225prompting with `> '. (Processing of arguments and the use of the shell to
226process files containing command scripts are described later.)
227The shell repeatedly reads a line of command input, breaks it into words,
228places it on the command history list, parses it and executes each command
229in the line.
230.PP
231One can log out by typing `^D' on an empty line, `logout' or `login' or
232via the shell's autologout mechanism (see the \fBautologout\fR shell variable).
233When a login shell terminates it sets the \fBlogout\fR shell variable to
234`normal' or `automatic' as appropriate, then
235executes commands from the files
236\fI/etc/csh.logout\fR and \fI~/.logout\fR. The shell may drop DTR on logout
237if so compiled; see the \fBversion\fR shell variable.
238.PP
239The names of the system login and logout files vary from system to system for
240compatibility with different \fIcsh\fR(1) variants; see \fBFILES\fR.
241.SS Editing
242We first describe \fBThe command-line editor\fR.
243The \fBCompletion and listing\fR and \fBSpelling correction\fR sections
244describe two sets of functionality that are implemented as editor commands
245but which deserve their own treatment.
246Finally, \fBEditor commands\fR lists and describes
247the editor commands specific to the shell and their default bindings.
248.SS "The command-line editor (+)"
249Command-line input can be edited using key sequences much like those used in
250GNU Emacs or \fIvi\fR(1).
251The editor is active only when the \fBedit\fR shell variable is set, which
252it is by default in interactive shells.
253The \fIbindkey\fR builtin can display and change key bindings.
254Emacs-style key bindings are used by default
255(unless the shell was compiled otherwise; see the \fBversion\fR shell variable),
256but \fIbindkey\fR can change the key bindings to \fIvi\fR-style bindings en masse.
257.PP
258The shell always binds the arrow keys (as defined in the \fBTERMCAP\fR
259environment variable) to
260.PP
261.PD 0
262.RS +4
263.TP 8
264down
265\fIdown-history\fR
266.TP 8
267up
268\fIup-history\fR
269.TP 8
270left
271\fIbackward-char\fR
272.TP 8
273right
274\fIforward-char\fR
275.PD
276.RE
277.PP
278unless doing so would alter another single-character binding.
279One can set the arrow key escape sequences to the empty string with \fIsettc\fR
280to prevent these bindings.
281The ANSI/VT100 sequences for arrow keys are always bound.
282.PP
283Other key bindings are, for the most part, what Emacs and \fIvi\fR(1)
284users would expect and can easily be displayed by \fIbindkey\fR, so there
285is no need to list them here. Likewise, \fIbindkey\fR can list the editor
286commands with a short description of each.
287.PP
288Note that editor commands do not have the same notion of a ``word'' as does the
289shell. The editor delimits words with any non-alphanumeric characters not in
290the shell variable \fBwordchars\fR, while the shell recognizes only whitespace
291and some of the characters with special meanings to it, listed under
292\fBLexical structure\fR.
293.SS "Completion and listing (+)"
294The shell is often able to complete words when given a unique abbreviation.
295Type part of a word (for example `ls /usr/lost') and hit the tab key to
296run the \fIcomplete-word\fR editor command.
297The shell completes the filename `/usr/lost' to `/usr/lost+found/',
298replacing the incomplete word with the complete word in the input buffer.
299(Note the terminal `/'; completion adds a `/' to the
300end of completed directories and a space to the end of other completed words,
301to speed typing and provide a visual indicator of successful completion.
302The \fBaddsuffix\fR shell variable can be unset to prevent this.)
303If no match is found (perhaps `/usr/lost+found' doesn't exist),
304the terminal bell rings.
305If the word is already complete (perhaps there is a `/usr/lost' on your
306system, or perhaps you were thinking too far ahead and typed the whole thing)
307a `/' or space is added to the end if it isn't already there.
308.PP
309Completion works anywhere in the line, not at just the end; completed
310text pushes the rest of the line to the right. Completion in the middle of a word
311often results in leftover characters to the right of the cursor that need
312to be deleted.
313.PP
314Commands and variables can be completed in much the same way.
315For example, typing `em[tab]' would complete `em' to
316`emacs' if \fIemacs\fR were the only command on your system beginning with `em'.
317Completion can find a command in any directory in \fBpath\fR or if
318given a full pathname.
319Typing `echo $ar[tab]' would complete `$ar' to `$argv'
320if no other variable began with `ar'.
321.PP
322The shell parses the input buffer to determine whether the word you want to
323complete should be completed as a filename, command or variable.
324The first word in the buffer and the first word following
325`;', `|', `|&', `&&' or `||' is considered to be a command.
326A word beginning with `$' is considered to be a variable.
327Anything else is a filename. An empty line is `completed' as a filename.
328.PP
329You can list the possible completions of a word at any time by typing `^D'
330to run the \fIdelete-char-or-list-or-eof\fR editor command.
331The shell lists the possible completions using the \fIls\-F\fR builtin (q.v.)
332and reprints the prompt and unfinished command line, for example:
333.IP "" 4
334> ls /usr/l[^D]
335.br
336lbin/ lib/ local/ lost+found/
337.br
338> ls /usr/l
339.PP
340If the \fBautolist\fR shell variable is set, the shell lists the remaining
341choices (if any) whenever completion fails:
342.IP "" 4
343> set autolist
344.br
345> nm /usr/lib/libt[tab]
346.br
347libtermcap.a@ libtermlib.a@
348.br
349> nm /usr/lib/libterm
350.PP
351If \fBautolist\fR is set to `ambiguous', choices are listed only when
352completion fails and adds no new characters to the word being completed.
353.PP
354A filename to be completed can contain variables, your own or others' home
355directories abbreviated with `~' (see \fBFilename substitution\fR) and
356directory stack entries abbreviated with `='
357(see \fBDirectory stack substitution\fR). For example,
358.IP "" 4
359> ls ~k[^D]
360.br
361kahn kas kellogg
362.br
363> ls ~ke[tab]
364.br
365> ls ~kellogg/
366.PP
367or
368.IP "" 4
369> set local = /usr/local
370.br
371> ls $lo[tab]
372.br
373> ls $local/[^D]
374.br
375bin/ etc/ lib/ man/ src/
376.br
377> ls $local/
378.PP
379Note that variables can also be expanded explicitly with the
380\fIexpand-variables\fR editor command.
381.PP
382\fIdelete-char-or-list-or-eof\fR lists at only the end of the line;
383in the middle of a line it deletes the character under the cursor and
384on an empty line it logs one out or, if \fBignoreeof\fR is set, does nothing.
385`M-^D', bound to the editor command \fIlist-choices\fR, lists completion
386possibilities anywhere on a line, and \fIlist-choices\fR (or any one of the
387related editor commands that do or don't delete, list and/or log out,
388listed under \fIdelete-char-or-list-or-eof\fR) can be bound to `^D' with
389the \fIbindkey\fR builtin command if so desired.
390.PP
391The \fIcomplete-word-fwd\fR and \fIcomplete-word-back\fR editor commands
392(not bound to any keys by default) can be used to cycle up and down through
393the list of possible completions, replacing the current word with the next or
394previous word in the list.
395.PP
396The shell variable \fBfignore\fR can be set to a list of suffixes to be
397ignored by completion. Consider the following:
398.IP "" 4
399> ls
400.br
401Makefile condiments.h~ main.o side.c
402.br
403README main.c meal side.o
404.br
405condiments.h main.c~
406.br
407> set fignore = (.o \\~)
408.br
409> emacs ma[^D]
410.br
411main.c main.c~ main.o
412.br
413> emacs ma[tab]
414.br
415> emacs main.c
416.PP
417`main.c~' and `main.o' are ignored by completion (but not listing),
418because they end in suffixes in \fBfignore\fR.
419Note that a `\\' was needed in front of `~' to prevent it from being
420expanded to \fBhome\fR as described under \fBFilename substitution\fR.
421\fBfignore\fR is ignored if only one completion is possible.
422.PP
423If the \fBcomplete\fR shell variable is set to `enhance', completion
4241) ignores case and 2) considers periods, hyphens and underscores
425(`.', `\-' and `_') to be word separators and hyphens and underscores to
426be equivalent. If you had the following files
427.IP "" 4
428comp.lang.c comp.lang.perl comp.std.c++
429.br
430comp.lang.c++ comp.std.c
431.PP
432and typed `mail \-f c.l.c[tab]', it would be completed to
433`mail \-f comp.lang.c', and ^D would list `comp.lang.c' and `comp.lang.c++'.
434`mail \-f c..c++[^D]' would list `comp.lang.c++' and `comp.std.c++'. Typing
435`rm a\-\-file[^D]' in the following directory
436.IP "" 4
437A_silly_file a-hyphenated-file another_silly_file
438.PP
439would list all three files, because case is ignored and hyphens and
440underscores are equivalent. Periods, however, are not equivalent to
441hyphens or underscores.
442.PP
443Completion and listing are affected by several other shell variables:
444\fBrecexact\fR can be set to complete on the shortest possible unique
445match, even if more typing might result in a longer match:
446.IP "" 4
447> ls
448.br
449fodder foo food foonly
450.br
451> set recexact
452.br
453> rm fo[tab]
454.PP
455just beeps, because `fo' could expand to `fod' or `foo', but if we type
456another `o',
457.IP "" 4
458> rm foo[tab]
459.br
460> rm foo
461.PP
462the completion completes on `foo', even though `food' and `foonly'
463also match.
464\fBautoexpand\fR can be set to run the \fIexpand-history\fR editor command
465before each completion attempt, \fBautocorrect\fR can be set to
466spelling-correct the word to be completed (see \fBSpelling correction\fR)
467before each completion attempt and \fBcorrect\fR can be set to complete
468commands automatically after one hits `return'.
469\fBmatchbeep\fR can be set to make completion beep or not beep in a variety
470of situations, and \fBnobeep\fR can be set to never beep at all.
471\fBnostat\fR can be set to a list of directories and/or patterns that
472match directories to prevent the completion mechanism from \fIstat\fR(2)ing
473those directories.
474\fBlistmax\fR and \fBlistmaxrows\fR can be set to limit the number of items
475and rows (respectively) that are listed without asking first.
476\fBrecognize_only_executables\fR can be set to make the shell list only
477executables when listing commands, but it is quite slow.
478.PP
479Finally, the \fIcomplete\fR builtin command can be used to tell the shell how
480to complete words other than filenames, commands and variables.
481Completion and listing do not work on glob-patterns (see \fBFilename substitution\fR),
482but the \fIlist-glob\fR and \fIexpand-glob\fR editor commands perform
483equivalent functions for glob-patterns.
484.SS "Spelling correction (+)"
485The shell can sometimes correct the spelling of filenames, commands and variable names
486as well as completing and listing them.
487.PP
488Individual words can be spelling-corrected with the \fIspell-word\fR
489editor command (usually bound to M-s and M-S)
490and the entire input buffer with \fIspell-line\fR (usually bound to M-$).
491The \fBcorrect\fR shell variable can be set to `cmd' to correct the
492command name or `all' to correct the entire line each time return is typed,
493and \fBautocorrect\fR can be set to correct the word to be completed
494before each completion attempt.
495.PP
496When spelling correction is invoked in any of these ways and
497the shell thinks that any part of the command line is misspelled,
498it prompts with the corrected line:
499.IP "" 4
500> set correct = cmd
501.br
502> lz /usr/bin
503.br
504CORRECT>ls /usr/bin (y|n|e|a)?
505.PP
506One can answer `y' or space to execute the corrected line,
507`e' to leave the uncorrected command in the input buffer,
508`a' to abort the command as if `^C' had been hit, and
509anything else to execute the original line unchanged.
510.PP
511Spelling correction recognizes user-defined completions (see the
512\fIcomplete\fR builtin command). If an input word in a position for
513which a completion is defined resembles a word in the completion list,
514spelling correction registers a misspelling and suggests the latter
515word as a correction. However, if the input word does not match any of
516the possible completions for that position, spelling correction does
517not register a misspelling.
518.PP
519Like completion, spelling correction works anywhere in the line,
520pushing the rest of the line to the right and possibly leaving
521extra characters to the right of the cursor.
522.PP
523Beware: spelling correction is not guaranteed to work the way one intends,
524and is provided mostly as an experimental feature.
525Suggestions and improvements are welcome.
526.SS "Editor commands (+)"
527`bindkey' lists key bindings and `bindkey \-l' lists and briefly describes
528editor commands.
529Only new or especially interesting editor commands are described here.
530See \fIemacs\fR(1) and \fIvi\fR(1) for descriptions of each editor's
531key bindings.
532.PP
533The character or characters to which each command is bound by default is
534given in parentheses. `^\fIcharacter\fR' means a control character and
535`M-\fIcharacter\fR' a meta character, typed as escape-\fIcharacter\fR
536on terminals without a meta key. Case counts, but commands that are bound
537to letters by default are bound to both lower- and uppercase letters for
538convenience.
539.TP 8
540.B complete-word \fR(tab)
541Completes a word as described under \fBCompletion and listing\fR.
542.TP 8
543.B complete-word-back \fR(not bound)
544Like \fIcomplete-word-fwd\fR, but steps up from the end of the list.
545.TP 8
546.B complete-word-fwd \fR(not bound)
547Replaces the current word with the first word in the list of possible
548completions. May be repeated to step down through the list.
549At the end of the list, beeps and reverts to the incomplete word.
550.TP 8
551.B complete-word-raw \fR(^X-tab)
552Like \fIcomplete-word\fR, but ignores user-defined completions.
553.TP 8
554.B copy-prev-word \fR(M-^_)
555Copies the previous word in the current line into the input buffer.
556See also \fIinsert-last-word\fR.
557.TP 8
558.B dabbrev-expand \fR(M-/)
559Expands the current word to the most recent preceding one for which
560the current is a leading substring, wrapping around the history list
561(once) if necessary.
562Repeating \fIdabbrev-expand\fR without any intervening typing
563changes to the next previous word etc., skipping identical matches
564much like \fIhistory-search-backward\fR does.
565.TP 8
566.B delete-char \fR(not bound)
567Deletes the character under the cursor.
568See also \fIdelete-char-or-list-or-eof\fR.
569.TP 8
570.B delete-char-or-eof \fR(not bound)
571Does \fIdelete-char\fR if there is a character under the cursor
572or \fIend-of-file\fR on an empty line.
573See also \fIdelete-char-or-list-or-eof\fR.
574.TP 8
575.B delete-char-or-list \fR(not bound)
576Does \fIdelete-char\fR if there is a character under the cursor
577or \fIlist-choices\fR at the end of the line.
578See also \fIdelete-char-or-list-or-eof\fR.
579.TP 8
580.B delete-char-or-list-or-eof \fR(^D)
581Does \fIdelete-char\fR if there is a character under the cursor,
582\fIlist-choices\fR at the end of the line
583or \fIend-of-file\fR on an empty line.
584See also those three commands, each of which does only a single action, and
585\fIdelete-char-or-eof\fR, \fIdelete-char-or-list\fR and \fIlist-or-eof\fR,
586each of which does a different two out of the three.
587.TP 8
588.B down-history \fR(down-arrow, ^N)
589Like \fIup-history\fR, but steps down, stopping at the original input line.
590.TP 8
591.B end-of-file \fR(not bound)
592Signals an end of file, causing the shell to exit unless the \fBignoreeof\fR
593shell variable (q.v.) is set to prevent this.
594See also \fIdelete-char-or-list-or-eof\fR.
595.TP 8
596.B expand-history \fR(M-space)
597Expands history substitutions in the current word.
598See \fBHistory substitution\fR.
599See also \fImagic-space\fR, \fItoggle-literal-history\fR and
600the \fBautoexpand\fR shell variable.
601.TP 8
602.B expand-glob \fR(^X-*)
603Expands the glob-pattern to the left of the cursor.
604See \fBFilename substitution\fR.
605.TP 8
606.B expand-line \fR(not bound)
607Like \fIexpand-history\fR, but
608expands history substitutions in each word in the input buffer,
609.TP 8
610.B expand-variables \fR(^X-$)
611Expands the variable to the left of the cursor.
612See \fBVariable substitution\fR.
613.TP 8
614.B history-search-backward \fR(M-p, M-P)
615Searches backwards through the history list for a command beginning with
616the current contents of the input buffer up to the cursor and copies it
617into the input buffer.
618The search string may be a glob-pattern (see \fBFilename substitution\fR)
619containing `*', `?', `[]' or `{}'.
620\fIup-history\fR and \fIdown-history\fR will proceed from the
621appropriate point in the history list.
622Emacs mode only.
623See also \fIhistory-search-forward\fR and \fIi-search-back\fR.
624.TP 8
625.B history-search-forward \fR(M-n, M-N)
626Like \fIhistory-search-backward\fR, but searches forward.
627.TP 8
628.B i-search-back \fR(not bound)
629Searches backward like \fIhistory-search-backward\fR, copies the first match
630into the input buffer with the cursor positioned at the end of the pattern,
631and prompts with `bck: ' and the first match. Additional characters may be
632typed to extend the search, \fIi-search-back\fR may be typed to continue
633searching with the same pattern, wrapping around the history list if
634necessary, (\fIi-search-back\fR must be bound to a
635single character for this to work) or one of the following special characters
636may be typed:
637.PP
638.RS +8
639.RS +4
640.PD 0
641.TP 8
642^W
643Appends the rest of the word under the cursor to the search pattern.
644.TP 8
645delete (or any character bound to \fIbackward-delete-char\fR)
646Undoes the effect of the last character typed and deletes a character
647from the search pattern if appropriate.
648.TP 8
649^G
650If the previous search was successful, aborts the entire search.
651If not, goes back to the last successful search.
652.TP 8
653escape
654Ends the search, leaving the current line in the input buffer.
655.RE
656.PD
657.PP
658Any other character not bound to \fIself-insert-command\fR terminates the
659search, leaving the current line in the input buffer, and
660is then interpreted as normal input. In particular, a carriage return
661causes the current line to be executed.
662Emacs mode only.
663See also \fIi-search-fwd\fR and \fIhistory-search-backward\fR.
664.RE
665.TP 8
666.B i-search-fwd \fR(not bound)
667Like \fIi-search-back\fR, but searches forward.
668.TP 8
669.B insert-last-word \fR(M-_)
670Inserts the last word of the previous input line (`!$') into the input buffer.
671See also \fIcopy-prev-word\fR.
672.TP 8
673.B list-choices \fR(M-^D)
674Lists completion possibilities as described under \fBCompletion and listing\fR.
675See also \fIdelete-char-or-list-or-eof\fR and \fIlist-choices-raw\fR.
676.TP 8
677.B list-choices-raw \fR(^X-^D)
678Like \fIlist-choices\fR, but ignores user-defined completions.
679.TP 8
680.B list-glob \fR(^X-g, ^X-G)
681Lists (via the \fIls\-F\fR builtin) matches to the glob-pattern
682(see \fBFilename substitution\fR) to the left of the cursor.
683.TP 8
684.B list-or-eof \fR(not bound)
685Does \fIlist-choices\fR
686or \fIend-of-file\fR on an empty line.
687See also \fIdelete-char-or-list-or-eof\fR.
688.TP 8
689.B magic-space \fR(not bound)
690Expands history substitutions in the current line,
691like \fIexpand-history\fR, and appends a space.
692\fImagic-space\fR is designed to be bound to the space bar,
693but is not bound by default.
694.TP 8
695.B normalize-command \fR(^X-?)
696Searches for the current word in PATH and, if it is found, replaces it with
697the full path to the executable. Special characters are quoted. Aliases are
698expanded and quoted but commands within aliases are not. This command is
699useful with commands that take commands as arguments, e.g., `dbx' and `sh \-x'.
700.TP 8
701.B normalize-path \fR(^X-n, ^X-N)
702Expands the current word as described under the `expand' setting
703of the \fBsymlinks\fR shell variable.
704.TP 8
705.B overwrite-mode \fR(unbound)
706Toggles between input and overwrite modes.
707.TP 8
708.B run-fg-editor \fR(M-^Z)
709Saves the current input line and
710looks for a stopped job with a name equal to the last component of the
711file name part of the \fBEDITOR\fR or \fBVISUAL\fR environment variables,
712or, if neither is set, `ed' or `vi'.
713If such a job is found, it is restarted as if `fg %\fIjob\fR' had been
714typed. This is used to toggle back and forth between an editor and
715the shell easily. Some people bind this command to `^Z' so they
716can do this even more easily.
717.TP
718.B run-help \fR(M-h, M-H)
719Searches for documentation on the current command, using the same notion of
720`current command' as the completion routines, and prints it. There is no way
721to use a pager; \fIrun-help\fR is designed for short help files.
722If the special alias \fBhelpcommand\fR is defined, it is run with the
723command name as a sole argument. Else,
724documentation should be in a file named \fIcommand\fR.help, \fIcommand\fR.1,
725\fIcommand\fR.6, \fIcommand\fR.8 or \fIcommand\fR, which should be in one
726of the directories listed in the \fBHPATH\fR environment variable.
727If there is more than one help file only the first is printed.
728.TP 8
729.B self-insert-command \fR(text characters)
730In insert mode (the default), inserts the typed character into the input line after the character under the cursor.
731In overwrite mode, replaces the character under the cursor with the typed character.
732The input mode is normally preserved between lines, but the
733\fBinputmode\fR shell variable can be set to `insert' or `overwrite' to put the
734editor in that mode at the beginning of each line.
735See also \fIoverwrite-mode\fR.
736.TP 8
737.B sequence-lead-in \fR(arrow prefix, meta prefix, ^X)
738Indicates that the following characters are part of a
739multi-key sequence. Binding a command to a multi-key sequence really creates
740two bindings: the first character to \fIsequence-lead-in\fR and the
741whole sequence to the command. All sequences beginning with a character
742bound to \fIsequence-lead-in\fR are effectively bound to \fIundefined-key\fR
743unless bound to another command.
744.TP 8
745.B spell-line \fR(M-$)
746Attempts to correct the spelling of each word in the input buffer, like
747\fIspell-word\fR, but ignores words whose first character is one of
748`\-', `!', `^' or `%', or which contain `\\', `*' or `?', to avoid problems
749with switches, substitutions and the like.
750See \fBSpelling correction\fR.
751.TP 8
752.B spell-word \fR(M-s, M-S)
753Attempts to correct the spelling of the current word as described
754under \fBSpelling correction\fR.
755Checks each component of a word which appears to be a pathname.
756.TP 8
757.B toggle-literal-history \fR(M-r, M-R)
758Expands or `unexpands' history substitutions in the input buffer.
759See also \fIexpand-history\fR and the \fBautoexpand\fR shell variable.
760.TP 8
761.B undefined-key \fR(any unbound key)
762Beeps.
763.TP 8
764.B up-history \fR(up-arrow, ^P)
765Copies the previous entry in the history list into the input buffer.
766If \fBhistlit\fR is set, uses the literal form of the entry.
767May be repeated to step up through the history list, stopping at the top.
768.TP 8
769.B vi-search-back \fR(?)
770Prompts with `?' for a search string (which may be a glob-pattern, as with
771\fIhistory-search-backward\fR), searches for it and copies it into the
772input buffer. The bell rings if no match is found.
773Hitting return ends the search and leaves the last match in the input
774buffer.
775Hitting escape ends the search and executes the match.
776\fIvi\fR mode only.
777.TP 8
778.B vi-search-fwd \fR(/)
779Like \fIvi-search-back\fR, but searches forward.
780.TP 8
781.B which-command \fR(M-?)
782Does a \fIwhich\fR (see the description of the builtin command) on the
783first word of the input buffer.
784.SS "Lexical structure"
785The shell splits input lines into words at blanks and tabs. The special
786characters `&', `|', `;', `<', `>', `(', and `)' and the doubled characters
787`&&', `||', `<<' and `>>' are always separate words, whether or not they are
788surrounded by whitespace.
789.PP
790When the shell's input is not a terminal, the character `#' is taken to begin a
791comment. Each `#' and the rest of the input line on which it appears is
792discarded before further parsing.
793.PP
794A special character (including a blank or tab) may be prevented from having
795its special meaning, and possibly made part of another word, by preceding it
796with a backslash (`\\') or enclosing it in single (`''), double (`"') or
797backward (``') quotes. When not otherwise quoted a newline preceded by a `\\'
798is equivalent to a blank, but inside quotes this sequence results in a
799newline.
800.PP
801Furthermore, all \fBSubstitutions\fR (see below) except \fBHistory substitution\fR
802can be prevented by enclosing the strings (or parts of strings)
803in which they appear with single quotes or by quoting the crucial character(s)
804(e.g., `$' or ``' for \fBVariable substitution\fR or \fBCommand substitution\fR respectively)
805with `\\'. (\fBAlias substitution\fR is no exception: quoting in any way any
806character of a word for which an \fIalias\fR has been defined prevents
807substitution of the alias. The usual way of quoting an alias is to precede it
808with a backslash.) \fBHistory substitution\fR is prevented by
809backslashes but not by single quotes. Strings quoted with double or backward
810quotes undergo \fBVariable substitution\fR and \fBCommand substitution\fR, but other
811substitutions are prevented.
812.PP
813Text inside single or double quotes becomes a single word (or part of one).
814Metacharacters in these strings, including blanks and tabs, do not form
815separate words. Only in one special case (see \fBCommand substitution\fR
816below) can a double-quoted string yield parts of more than one word;
817single-quoted strings never do. Backward quotes are special: they signal
818\fBCommand substitution\fR (q.v.), which may result in more than one word.
819.PP
820Quoting complex strings, particularly strings which themselves contain quoting
821characters, can be confusing. Remember that quotes need not be used as they are
822in human writing! It may be easier to quote not an entire string, but only
823those parts of the string which need quoting, using different types of quoting
824to do so if appropriate.
825.PP
826The \fBbackslash_quote\fR shell variable (q.v.) can be set to make backslashes
827always quote `\\', `'', and `"'. (+) This may make complex quoting tasks
828easier, but it can cause syntax errors in \fIcsh\fR(1) scripts.
829.SS Substitutions
830We now describe the various transformations the shell performs on the input in
831the order in which they occur. We note in passing the data structures involved
832and the commands and variables which affect them. Remember that substitutions
833can be prevented by quoting as described under \fBLexical structure\fR.
834.SS "History substitution"
835Each command, or ``event'', input from the terminal is saved in the history
836list. The previous command is always saved, and the \fBhistory\fR shell
837variable can be set to a number to save that many commands. The \fBhistdup\fR
838shell variable can be set to not save duplicate events or consecutive duplicate
839events.
840.PP
841Saved commands are numbered sequentially from 1 and stamped with the time.
842It is not usually necessary to use event numbers, but the current event number
843can be made part of the prompt by placing an `!' in the \fBprompt\fR shell variable.
844.PP
845The shell actually saves history in expanded and literal (unexpanded) forms.
846If the \fBhistlit\fR shell variable is set, commands that display and store
847history use the literal form.
848.PP
849The \fIhistory\fR builtin command can print, store in a file, restore
850and clear the history list at any time,
851and the \fBsavehist\fR and \fBhistfile\fR shell variables can be can be set to
852store the history list automatically on logout and restore it on login.
853.PP
854History substitutions introduce words from the history list into the input
855stream, making it easy to repeat commands, repeat arguments of a previous
856command in the current command, or fix spelling mistakes in the previous
857command with little typing and a high degree of confidence.
858.PP
859History substitutions begin with the character `!'. They may begin anywhere in
860the input stream, but they do not nest. The `!' may be preceded by a `\\' to
861prevent its special meaning; for convenience, a `!' is passed unchanged when it
862is followed by a blank, tab, newline, `=' or `('. History substitutions also
863occur when an input line begins with `^'. This special abbreviation will be
864described later. The characters used to signal history substitution (`!' and
865`^') can be changed by setting the \fBhistchars\fR shell variable. Any input
866line which contains a history substitution is printed before it is executed.
867.PP
868A history substitution may have an ``event specification'', which indicates
869the event from which words are to be taken, a ``word designator'',
870which selects particular words from the chosen event, and/or a ``modifier'',
871which manipulates the selected words.
872.PP
873An event specification can be
874.PP
875.PD 0
876.RS +4
877.TP 8
878.I n
879A number, referring to a particular event
880.TP 8
881\-\fIn\fR
882An offset, referring to the event \fIn\fR before the current event
883.TP 8
884#
885The current event.
886This should be used carefully in \fIcsh\fR(1), where there is no check for
887recursion. \fItcsh\fR allows 10 levels of recursion. (+)
888.TP 8
889!
890The previous event (equivalent to `\-1')
891.TP 8
892.I s
893The most recent event whose first word begins with the string \fIs\fR
894.TP 8
895?\fIs\fR?
896The most recent event which contains the string \fIs\fR.
897The second `?' can be omitted if it is immediately followed by a newline.
898.RE
899.PD
900.PP
901For example, consider this bit of someone's history list:
902.IP "" 4
903\ 9 8:30 nroff \-man wumpus.man
904.br
90510 8:31 cp wumpus.man wumpus.man.old
906.br
90711 8:36 vi wumpus.man
908.br
90912 8:37 diff wumpus.man.old wumpus.man
910.PP
911The commands are shown with their event numbers and time stamps.
912The current event, which we haven't typed in yet, is event 13.
913`!11' and `!\-2' refer to event 11.
914`!!' refers to the previous event, 12. `!!' can be abbreviated `!' if it is
915followed by `:' (`:' is described below).
916`!n' refers to event 9, which begins with `n'.
917`!?old?' also refers to event 12, which contains `old'.
918Without word designators or modifiers history references simply expand to the
919entire event, so we might type `!cp' to redo the copy command or `!!|more'
920if the `diff' output scrolled off the top of the screen.
921.PP
922History references may be insulated from the surrounding text with braces if
923necessary. For example, `!vdoc' would look for a command beginning with
924`vdoc', and, in this example, not find one, but `!{v}doc' would expand
925unambiguously to `vi wumpus.mandoc'.
926Even in braces, history substitutions do not nest.
927.PP
928(+) While \fIcsh\fR(1) expands, for example, `!3d' to event 3 with the
929letter `d' appended to it, \fItcsh\fR expands it to the last event beginning
930with `3d'; only completely numeric arguments are treated as event numbers.
931This makes it possible to recall events beginning with numbers.
932To expand `!3d' as in \fIcsh\fR(1) say `!\\3d'.
933.PP
934To select words from an event we can follow the event specification by a `:'
935and a designator for the desired words. The words of an input line are
936numbered from 0, the first (usually command) word being 0, the second word
937(first argument) being 1, etc. The basic word designators are:
938.PP
939.PD 0
940.RS +4
941.TP 8
9420
943The first (command) word
944.TP 8
945.I n
946The \fIn\fRth argument
947.TP 8
948^
949The first argument, equivalent to `1'
950.TP 8
951$
952The last argument
953.TP 8
954%
955The word matched by an ?\fIs\fR? search
956.TP 8
957.I x\-y
958A range of words
959.TP 8
960.I \-y
961Equivalent to \fI`0\-y'\fR
962.TP 8
963*
964Equivalent to `^\-$', but returns nothing if the event contains only 1 word
965.TP 8
966.I x*
967Equivalent to \fI`x\-$'\fR
968.TP 8
969.I x\-
970Equivalent to \fI`x*'\fR, but omitting the last word (`$')
971.PD
972.RE
973.PP
974Selected words are inserted into the command line separated by single blanks.
975For example, the `diff' command in the previous example might have been
976typed as `diff !!:1.old !!:1' (using `:1' to select the first argument
977from the previous event) or `diff !\-2:2 !\-2:1' to select and swap the
978arguments from the `cp' command. If we didn't care about the order of the
979`diff' we might have said `diff !\-2:1\-2' or simply `diff !\-2:*'.
980The `cp' command might have been written `cp wumpus.man !#:1.old', using `#'
981to refer to the current event.
982`!n:\- hurkle.man' would reuse the first two words from the `nroff' command
983to say `nroff \-man hurkle.man'.
984.PP
985The `:' separating the event specification from the word designator can be
986omitted if the argument selector begins with a `^', `$', `*', `%' or `\-'.
987For example, our `diff' command might have been `diff !!^.old !!^' or,
988equivalently, `diff !!$.old !!$'. However, if `!!' is abbreviated `!',
989an argument selector beginning with `\-' will be interpreted as an event
990specification.
991.PP
992A history reference may have a word designator but no event specification.
993It then references the previous command.
994.ig \" Not true, but we thought it was for a long time ...
995, unless a previous history reference
996occurred on the same line in which case this form repeats the previous
997reference. Thus `!?foo?^ !$' gives the first and last arguments from the
998command matching `?foo?'.
999..
1000Continuing our `diff' example, we could have said simply `diff
1001!^.old !^' or, to get the arguments in the opposite order, just `diff !*'.
1002.PP
1003The word or words in a history reference can be edited, or ``modified'',
1004by following it with one or more modifiers, each preceded by a `:':
1005.PP
1006.PD 0
1007.RS +4
1008.TP 8
1009h
1010Remove a trailing pathname component, leaving the head.
1011.TP 8
1012t
1013Remove all leading pathname components, leaving the tail.
1014.TP 8
1015r
1016Remove a filename extension `.xxx', leaving the root name.
1017.TP 8
1018e
1019Remove all but the extension.
1020.TP 8
1021u
1022Uppercase the first lowercase letter.
1023.TP 8
1024l
1025Lowercase the first uppercase letter.
1026.TP 8
1027s\fI/l/r/\fR
1028Substitute \fIl\fR for \fIr\fR.
1029\fIl\fR is simply a string like \fIr\fR, not a regular expression as in
1030the eponymous \fIed\fR(1) command.
1031Any character may be used as the delimiter in place of `/';
1032a `\\' can be used to quote the delimiter inside \fIl\fR and \fIr\fR.
1033The character `&' in the \fIr\fR is replaced by \fIl\fR; `\\' also quotes `&'.
1034If \fIl\fR is empty (``''), the \fIl\fR from a previous substitution or the
1035\fIs\fR from a previous `?\fIs\fR?' event specification is used.
1036The trailing delimiter may be omitted if it is immediately followed by a newline.
1037.TP 8
1038&
1039Repeat the previous substitution.
1040.TP 8
1041g
1042Apply the following modifier once to each word.
1043.TP 8
1044a (+)
1045Apply the following modifier as many times as possible to a single word.
1046`a' and `g' can be used together to apply a modifier globally.
1047In the current implementation, using the `a' and `s' modifiers together can
1048lead to an infinite loop. For example, `:as/f/ff/' will never terminate.
1049This behavior might change in the future.
1050.TP 8
1051p
1052Print the new command line but do not execute it.
1053.TP 8
1054q
1055Quote the substituted words, preventing further substitutions.
1056.TP 8
1057x
1058Like q, but break into words at blanks, tabs and newlines.
1059.PD
1060.RE
1061.PP
1062Modifiers are applied to only the first modifiable word (unless `g' is used).
1063It is an error for no word to be modifiable.
1064.PP
1065For example, the `diff' command might have been written as `diff wumpus.man.old
1066!#^:r', using `:r' to remove `.old' from the first argument on the same line
1067(`!#^'). We could say `echo hello out there', then `echo !*:u' to capitalize
1068`hello', `echo !*:au' to say it out loud, or `echo !*:agu' to really shout.
1069We might follow `mail \-s "I forgot my password" rot' with `!:s/rot/root' to
1070correct the spelling of `root' (but see \fBSpelling correction\fR for a
1071different approach).
1072.PP
1073There is a special abbreviation for substitutions.
1074`^', when it is the first character on an input line, is equivalent to `!:s^'.
1075Thus we might have said `^rot^root' to make the spelling correction in the
1076previous example.
1077This is the only history substitution which does not explicitly begin with `!'.
1078.PP
1079(+) In \fIcsh\fR as such, only one modifier may be applied to each history
1080or variable expansion. In \fItcsh\fR, more than one may be used, for example
1081.IP "" 4
1082% mv wumpus.man /usr/man/man1/wumpus.1
1083.br
1084% man !$:t:r
1085.br
1086man wumpus
1087.PP
1088In \fIcsh\fR, the result would be `wumpus.1:r'. A substitution followed by a
1089colon may need to be insulated from it with braces:
1090.IP "" 4
1091> mv a.out /usr/games/wumpus
1092.br
1093> setenv PATH !$:h:$PATH
1094.br
1095Bad ! modifier: $.
1096.br
1097> setenv PATH !{\-2$:h}:$PATH
1098.br
1099setenv PATH /usr/games:/bin:/usr/bin:.
1100.PP
1101The first attempt would succeed in \fIcsh\fR but fails in \fItcsh\fR,
1102because \fItcsh\fR expects another modifier after the second colon
1103rather than `$'.
1104.PP
1105Finally, history can be accessed through the editor as well as through
1106the substitutions just described.
1107The \fIup-\fR and \fIdown-history\fR, \fIhistory-search-backward\fR and
1108\fI-forward\fR, \fIi-search-back\fR and \fI-fwd\fR,
1109\fIvi-search-back\fR and \fI-fwd\fR, \fIcopy-prev-word\fR
1110and \fIinsert-last-word\fR editor commands search for
1111events in the history list and copy them into the input buffer.
1112The \fItoggle-literal-history\fR editor command switches between the
1113expanded and literal forms of history lines in the input buffer.
1114\fIexpand-history\fR and \fIexpand-line\fR expand history substitutions
1115in the current word and in the entire input buffer respectively.
1116.SS "Alias substitution"
1117The shell maintains a list of aliases which can be set, unset and printed by
1118the \fIalias\fR and \fIunalias\fR commands. After a command line is parsed
1119into simple commands (see \fBCommands\fR) the first word of each command,
1120left-to-right, is checked to see if it has an alias. If so, the first word is
1121replaced by the alias. If the alias contains a history reference, it undergoes
1122\fBHistory substitution\fR (q.v.) as though the original command were the
1123previous input line. If the alias does not contain a history reference, the
1124argument list is left untouched.
1125.PP
1126Thus if the alias for `ls' were `ls \-l' the command `ls /usr' would become `ls
1127\-l /usr', the argument list here being undisturbed. If the alias for `lookup'
1128were `grep !^ /etc/passwd' then `lookup bill' would become `grep bill
1129/etc/passwd'. Aliases can be used to introduce parser metasyntax. For
1130example, `alias print 'pr \e!* | lpr'' defines a ``command'' (`print') which
1131\fIpr\fR(1)s its arguments to the line printer.
1132.PP
1133Alias substitution is repeated until the first word of the command has no
1134alias. If an alias substitution does not change the first word (as in the
1135previous example) it is flagged to prevent a loop. Other loops are detected and
1136cause an error.
1137.PP
1138Some aliases are referred to by the shell; see \fBSpecial aliases\fR.
1139.SS "Variable substitution"
1140The shell maintains a list of variables, each of which has as value a list of
1141zero or more words.
1142The values of shell variables can be displayed and changed with the
1143\fIset\fR and \fIunset\fR commands.
1144The system maintains its own list of ``environment'' variables.
1145These can be displayed and changed with \fIprintenv\fR, \fIsetenv\fR and
1146\fIunsetenv\fR.
1147.PP
1148(+) Variables may be made read-only with `set \-r' (q.v.)
1149Read-only variables may not be modified or unset;
1150attempting to do so will cause an error.
1151Once made read-only, a variable cannot be made writable,
1152so `set \-r' should be used with caution.
1153Environment variables cannot be made read-only.
1154.PP
1155Some variables are set by the shell or referred to by it.
1156For instance, the \fBargv\fR variable is an image of the shell's argument
1157list, and words of this variable's value are referred to in special ways.
1158Some of the variables referred to by the shell are toggles;
1159the shell does not care what their value is, only whether they are set or not.
1160For instance, the \fBverbose\fR variable is a toggle which causes command
1161input to be echoed. The \fB\-v\fR command line option sets this variable.
1162\fBSpecial shell variables\fR lists all variables which are referred to by the shell.
1163.PP
1164Other operations treat variables numerically. The `@' command permits numeric
1165calculations to be performed and the result assigned to a variable. Variable
1166values are, however, always represented as (zero or more) strings. For the
1167purposes of numeric operations, the null string is considered to be zero, and
1168the second and subsequent words of multi-word values are ignored.
1169.PP
1170After the input line is aliased and parsed, and before each command is
1171executed, variable substitution is performed keyed by `$' characters. This
1172expansion can be prevented by preceding the `$' with a `\e' except within `"'s
1173where it \fIalways\fR occurs, and within `''s where it \fInever\fR occurs.
1174Strings quoted by ``' are interpreted later (see \fBCommand substitution\fR
1175below) so `$' substitution does not occur there until later,
1176if at all. A `$' is passed unchanged if followed by a blank, tab, or
1177end-of-line.
1178.PP
1179Input/output redirections are recognized before variable expansion, and are
1180variable expanded separately. Otherwise, the command name and entire argument
1181list are expanded together. It is thus possible for the first (command) word
1182(to this point) to generate more than one word, the first of which becomes the
1183command name, and the rest of which become arguments.
1184.PP
1185Unless enclosed in `"' or given the `:q' modifier the results of variable
1186substitution may eventually be command and filename substituted. Within `"', a
1187variable whose value consists of multiple words expands to a (portion of a)
1188single word, with the words of the variable's value separated by blanks. When
1189the `:q' modifier is applied to a substitution the variable will expand to
1190multiple words with each word separated by a blank and quoted to prevent later
1191command or filename substitution.
1192.PP
1193The following metasequences are provided for introducing variable values into
1194the shell input. Except as noted, it is an error to reference a variable which
1195is not set.
1196.PP
1197.PD 0
1198$\fIname\fR
1199.TP 8
1200${\fIname\fR}
1201Substitutes the words of the value of variable \fIname\fR, each separated
1202by a blank. Braces insulate \fIname\fR from following characters which would
1203otherwise be part of it. Shell variables have names consisting of up to 20
1204letters and digits starting with a letter. The underscore character is
1205considered a letter. If \fIname\fR is not a shell variable, but is set in the
1206environment, then that value is returned (but `:' modifiers and the other forms
1207given below are not available in this case).
1208.PP
1209$\fIname\fR[\fIselector\fR]
1210.TP 8
1211${\fIname\fR[\fIselector\fR]}
1212Substitutes only the selected words from the value of \fIname\fR.
1213The \fIselector\fR is subjected to `$' substitution and may consist of
1214a single number or two numbers separated by a `\-'.
1215The first word of a variable's value is numbered `1'.
1216If the first number of a range is omitted it defaults to `1'.
1217If the last member of a range is omitted it defaults to `$#\fIname\fR'.
1218The \fIselector\fR `*' selects all words.
1219It is not an error for a range to be empty if the
1220second argument is omitted or in range.
1221.TP 8
1222$0
1223Substitutes the name of the file from which command input
1224is being read. An error occurs if the name is not known.
1225.PP
1226$\fInumber\fR
1227.TP 8
1228${\fInumber\fR}
1229Equivalent to `$argv[\fInumber\fR]'.
1230.TP 8
1231$*
1232Equivalent to `$argv', which is equivalent to `$argv[*]'.
1233.PD
1234.PP
1235The `:' modifiers described under \fBHistory substitution\fR, except for `:p',
1236can be applied to the substitutions above. More than one may be used. (+)
1237Braces may be needed to insulate a variable substitution from a literal colon
1238just as with \fBHistory substitution\fR (q.v.); any modifiers must appear
1239within the braces.
1240.PP
1241The following substitutions can not be modified with `:' modifiers.
1242.PP
1243.PD 0
1244$?\fIname\fR
1245.TP 8
1246${?\fIname\fR}
1247Substitutes the string `1' if \fIname\fR is set, `0' if it is not.
1248.TP 8
1249$?0
1250Substitutes `1' if the current input filename is known, `0' if it is not.
1251Always `0' in interactive shells.
1252.PP
1253$#\fIname\fR
1254.TP 8
1255${#\fIname\fR}
1256Substitutes the number of words in \fIname\fR.
1257.TP 8
1258$#
1259Equivalent to `$#argv'. (+)
1260.PP
1261$%\fIname\fR
1262.TP 8
1263${%\fIname\fR}
1264Substitutes the number of characters in \fIname\fR. (+)
1265.PP
1266$%\fInumber\fR
1267.TP 8
1268${%\fInumber\fR}
1269Substitutes the number of characters in $argv[\fInumber\fR]. (+)
1270.TP 8
1271$?
1272Equivalent to `$status'. (+)
1273.TP 8
1274$$
1275Substitutes the (decimal) process number of the (parent) shell.
1276.TP 8
1277$!
1278Substitutes the (decimal) process number of the last
1279background process started by this shell. (+)
1280.TP 8
1281$_
1282Substitutes the command line of the last command executed. (+)
1283.TP 8
1284$<
1285Substitutes a line from the standard input, with no further interpretation
1286thereafter. It can be used to read from the keyboard in a shell script.
1287(+) While \fIcsh\fR always quotes $<, as if it were equivalent to `$<:q',
1288\fItcsh\fR does not. Furthermore, when \fItcsh\fR is waiting for a line to be
1289typed the user may type an interrupt to interrupt the sequence into
1290which the line is to be substituted, but \fIcsh\fR does not allow this.
1291.PD
1292.PP
1293The editor command \fIexpand-variables\fR, normally bound to `^X-$',
1294can be used to interactively expand individual variables.
1295.SS "Command, filename and directory stack substitution"
1296The remaining substitutions are applied selectively to the arguments of builtin
1297commands. This means that portions of expressions which are not evaluated are
1298not subjected to these expansions. For commands which are not internal to the
1299shell, the command name is substituted separately from the argument list. This
1300occurs very late, after input-output redirection is performed, and in a child
1301of the main shell.
1302.SS "Command substitution"
1303Command substitution is indicated by a command enclosed in ``'. The output
1304from such a command is broken into separate words at blanks, tabs and newlines,
1305and null words are discarded. The output is variable and command substituted
1306and put in place of the original string.
1307.PP
1308Command substitutions inside double
1309quotes (`"') retain blanks and tabs; only newlines force new words. The single
1310final newline does not force a new word in any case. It is thus possible for a
1311command substitution to yield only part of a word, even if the command outputs
1312a complete line.
1313.SS "Filename substitution"
1314If a word contains any of the characters `*', `?', `[' or `{' or begins with
1315the character `~' it is a candidate for filename substitution, also known as
1316``globbing''. This word is then regarded as a pattern (``glob-pattern''), and
1317replaced with an alphabetically sorted list of file names which match the
1318pattern.
1319.PP
1320In matching filenames, the character `.' at the beginning of a filename or
1321immediately following a `/', as well as the character `/' must be matched
1322explicitly. The character `*' matches any string of characters, including the
1323null string. The character `?' matches any single character. The sequence
1324`[...]' matches any one of the characters enclosed. Within `[...]', a pair of
1325characters separated by `\-' matches any character lexically between the two.
1326.PP
1327(+) Some glob-patterns can be negated:
1328The sequence `[^...]' matches any single character \fInot\fR specified by the
1329characters and/or ranges of characters in the braces.
1330.PP
1331An entire glob-pattern can also be negated with `^':
1332.IP "" 4
1333> echo *
1334.br
1335bang crash crunch ouch
1336.br
1337> echo ^cr*
1338.br
1339bang ouch
1340.PP
1341Glob-patterns which do not use `?', `*', or `[]' or which use `{}' or `~'
1342(below) are not negated correctly.
1343.PP
1344The metanotation `a{b,c,d}e' is a shorthand for `abe ace ade'.
1345Left-to-right order is preserved: `/usr/source/s1/{oldls,ls}.c' expands
1346to `/usr/source/s1/oldls.c /usr/source/s1/ls.c'. The results of matches are
1347sorted separately at a low level to preserve this order:
1348`../{memo,*box}' might expand to `../memo ../box ../mbox'.
1349(Note that `memo' was not sorted with the results of matching `*box'.)
1350It is not an error when this construct expands to files which do not exist,
1351but it is possible to get an error from a command to which the expanded list
1352is passed.
1353This construct may be nested.
1354As a special case the words `{', `}' and `{}' are passed undisturbed.
1355.PP
1356The character `~' at the beginning of a filename refers to home directories.
1357Standing alone, i.e., `~', it expands to the invoker's home directory as
1358reflected in the value of the \fBhome\fR shell variable. When followed by a
1359name consisting of letters, digits and `\-' characters the shell searches for a
1360user with that name and substitutes their home directory; thus `~ken' might
1361expand to `/usr/ken' and `~ken/chmach' to `/usr/ken/chmach'. If the character
1362`~' is followed by a character other than a letter or `/' or appears elsewhere
1363than at the beginning of a word, it is left undisturbed.
1364A command like `setenv MANPATH /usr/man:/usr/local/man:~/lib/man' does not,
1365therefore, do home directory substitution as one might hope.
1366.PP
1367It is an error for a glob-pattern containing `*', `?', `[' or `~', with or
1368without `^', not to match any files. However, only one pattern in a list of
1369glob-patterns must match a file (so that, e.g., `rm *.a *.c *.o' would fail
1370only if there were no files in the current directory ending in `.a', `.c', or
1371`.o'), and if the \fBnonomatch\fR shell variable is set a pattern (or list
1372of patterns) which matches nothing is left unchanged rather than causing
1373an error.
1374.PP
1375The \fBnoglob\fR shell variable can be set to prevent filename substitution,
1376and the \fIexpand-glob\fR editor command, normally bound to `^X-*', can be
1377used to interactively expand individual filename substitutions.
1378.SS "Directory stack substitution (+)"
1379The directory stack is a list of directories, numbered from zero, used by the
1380\fIpushd\fR, \fIpopd\fR and \fIdirs\fR builtin commands (q.v.).
1381\fIdirs\fR can print, store in a file, restore and clear the directory stack
1382at any time, and the \fBsavedirs\fR and \fBdirsfile\fR shell variables can be set to
1383store the directory stack automatically on logout and restore it on login.
1384The \fBdirstack\fR shell variable can be examined to see the directory stack and
1385set to put arbitrary directories into the directory stack.
1386.PP
1387The character `=' followed by one or more digits expands to an entry in
1388the directory stack. The special case `=\-' expands to the last directory in
1389the stack. For example,
1390.IP "" 4
1391> dirs \-v
1392.br
13930 /usr/bin
1394.br
13951 /usr/spool/uucp
1396.br
13972 /usr/accts/sys
1398.br
1399> echo =1
1400.br
1401/usr/spool/uucp
1402.br
1403> echo =0/calendar
1404.br
1405/usr/bin/calendar
1406.br
1407> echo =\-
1408.br
1409/usr/accts/sys
1410.PP
1411The \fBnoglob\fR and \fBnonomatch\fR shell variables and the \fIexpand-glob\fR
1412editor command apply to directory stack as well as filename substitutions.
1413.SS "Other substitutions (+)"
1414There are several more transformations involving filenames, not strictly
1415related to the above but mentioned here for completeness.
1416\fIAny\fR filename may be expanded to a full path when the
1417\fBsymlinks\fR variable (q.v.) is set to `expand'.
1418Quoting prevents this expansion, and
1419the \fInormalize-path\fR editor command does it on demand.
1420The \fInormalize-command\fR editor command expands commands in PATH into
1421full paths on demand.
1422Finally, \fIcd\fR and \fIpushd\fR interpret `\-' as the old working directory
1423(equivalent to the shell variable \fBowd\fR).
1424This is not a substitution at all, but an abbreviation recognized by only
1425those commands. Nonetheless, it too can be prevented by quoting.
1426.SS Commands
1427The next three sections describe how the shell executes commands and
1428deals with their input and output.
1429.SS Simple commands, pipelines and sequences
1430A simple command is a sequence of words, the first of which specifies the
1431command to be executed. A series of simple commands joined by `|' characters
1432forms a pipeline. The output of each command in a pipeline is connected to the
1433input of the next.
1434.PP
1435Simple commands and pipelines may be joined into sequences with `;', and will
1436be executed sequentially. Commands and pipelines can also be joined into
1437sequences with `||' or `&&', indicating, as in the C language, that the second
1438is to be executed only if the first fails or succeeds respectively.
1439.PP
1440A simple command, pipeline or sequence may be placed in parentheses, `()',
1441to form a simple command, which may in turn be a component of a pipeline or
1442sequence. A command, pipeline or sequence can be executed
1443without waiting for it to terminate by following it with an `&'.
1444.SS "Builtin and non-builtin command execution"
1445Builtin commands are executed within the shell. If any component of a
1446pipeline except the last is a builtin command, the pipeline is executed
1447in a subshell.
1448.PP
1449Parenthesized commands are always executed in a subshell.
1450.IP "" 4
1451(cd; pwd); pwd
1452.PP
1453thus prints the \fBhome\fR directory, leaving you where you were
1454(printing this after the home directory), while
1455.IP "" 4
1456cd; pwd
1457.PP
1458leaves you in the \fBhome\fR directory. Parenthesized commands are most often
1459used to prevent \fIcd\fR from affecting the current shell.
1460.PP
1461When a command to be executed is found not to be a builtin command the shell
1462attempts to execute the command via \fIexecve\fR(2). Each word in the variable
1463\fBpath\fR names a directory in which the shell will look for the
1464command. If it is given neither a \fB\-c\fR nor a \fB\-t\fR option, the shell
1465hashes the names in these directories into an internal table so that it will
1466try an \fIexecve\fR(2) in only a directory where there is a possibility that the
1467command resides there. This greatly speeds command location when a large
1468number of directories are present in the search path. If this mechanism has
1469been turned off (via \fIunhash\fR), if the shell was given a \fB\-c\fR or
1470\fB\-t\fR argument or in any case for each directory component of \fBpath\fR
1471which does not begin with a `/', the shell concatenates the current working
1472directory with the given command name to form a path name of a file which it
1473then attempts to execute.
1474.PP
1475If the file has execute permissions but is not an executable to the system
1476(i.e., it is neither an executable binary nor a script that specifies its
1477interpreter), then it is assumed to be a file containing shell commands and
1478a new shell is spawned to read it. The \fIshell\fR special alias may be set
1479to specify an interpreter other than the shell itself.
1480.PP
1481On systems which do not understand the `#!' script interpreter convention
1482the shell may be compiled to emulate it; see the \fBversion\fR shell
1483variable\fR. If so, the shell checks the first line of the file to
1484see if it is of the form `#!\fIinterpreter\fR \fIarg\fR ...'. If it is,
1485the shell starts \fIinterpreter\fR with the given \fIarg\fRs and feeds the
1486file to it on standard input.
1487.SS Input/output
1488The standard input and standard output of a command may be redirected with the
1489following syntax:
1490.PP
1491.PD 0
1492.TP 8
1493< \fIname
1494Open file \fIname\fR (which is first variable, command and filename
1495expanded) as the standard input.
1496.TP 8
1497<< \fIword
1498Read the shell input up to a line which is identical to \fIword\fR. \fIword\fR
1499is not subjected to variable, filename or command substitution, and each input
1500line is compared to \fIword\fR before any substitutions are done on this input
1501line. Unless a quoting `\e', `"', `' or ``' appears in \fIword\fR variable and
1502command substitution is performed on the intervening lines, allowing `\e' to
1503quote `$', `\e' and ``'. Commands which are substituted have all blanks, tabs,
1504and newlines preserved, except for the final newline which is dropped. The
1505resultant text is placed in an anonymous temporary file which is given to the
1506command as standard input.
1507.PP
1508> \fIname
1509.br
1510>! \fIname
1511.br
1512>& \fIname
1513.TP 8
1514>&! \fIname
1515The file \fIname\fR is used as standard output. If the file does not exist
1516then it is created; if the file exists, it is truncated, its previous contents
1517being lost.
1518.RS +8
1519.PD
1520.PP
1521If the shell variable \fBnoclobber\fR is set, then the file must not exist or be a
1522character special file (e.g., a terminal or `/dev/null') or an error results.
1523This helps prevent accidental destruction of files. In this case the `!' forms
1524can be used to suppress this check.
1525.PP
1526The forms involving `&' route the diagnostic output into the specified file as
1527well as the standard output. \fIname\fR is expanded in the same way as `<'
1528input filenames are.
1529.PD 0
1530.RE
1531.PP
1532>> \fIname
1533.br
1534>>& \fIname
1535.br
1536>>! \fIname
1537.TP 8
1538>>&! \fIname
1539Like `>', but appends output to the end of \fIname\fR.
1540If the shell variable \fBnoclobber\fR is set, then it is an error for
1541the file \fInot\fR to exist, unless one of the `!' forms is given.
1542.PD
1543.PP
1544A command receives the environment in which the shell was invoked as modified
1545by the input-output parameters and the presence of the command in a pipeline.
1546Thus, unlike some previous shells, commands run from a file of shell commands
1547have no access to the text of the commands by default; rather they receive the
1548original standard input of the shell. The `<<' mechanism should be used to
1549present inline data. This permits shell command scripts to function as
1550components of pipelines and allows the shell to block read its input. Note
1551that the default standard input for a command run detached is \fInot\fR
1552the empty file \fI/dev/null\fR, but the original standard input of the shell.
1553If this is a terminal and if the process attempts to read from the terminal,
1554then the process will block and the user will be notified (see \fBJobs\fR).
1555.PP
1556Diagnostic output may be directed through a pipe with the standard output.
1557Simply use the form `|&' rather than just `|'.
1558.PP
1559The shell cannot presently redirect diagnostic output without also redirecting
1560standard output, but `(\fIcommand\fR > \fIoutput-file\fR) >& \fIerror-file\fR'
1561is often an acceptable workaround. Either \fIoutput-file\fR or
1562\fIerror-file\fR may be `/dev/tty' to send output to the terminal.
1563.SS Features
1564Having described how the shell accepts, parses and executes
1565command lines, we now turn to a variety of its useful features.
1566.SS "Control flow"
1567The shell contains a number of commands which can be used to regulate the
1568flow of control in command files (shell scripts) and (in limited but
1569useful ways) from terminal input. These commands all operate by forcing the
1570shell to reread or skip in its input and, due to the implementation,
1571restrict the placement of some of the commands.
1572.PP
1573The \fIforeach\fR, \fIswitch\fR, and \fIwhile\fR statements, as well as the
1574\fIif-then-else\fR form of the \fIif\fR statement, require that the major
1575keywords appear in a single simple command on an input line as shown below.
1576.PP
1577If the shell's input is not seekable, the shell buffers up input whenever
1578a loop is being read and performs seeks in this internal buffer to
1579accomplish the rereading implied by the loop. (To the extent that this
1580allows, backward \fIgoto\fRs will succeed on non-seekable inputs.)
1581.SS Expressions
1582The \fIif\fR, \fIwhile\fR and \fIexit\fR builtin commands
1583use expressions with a common syntax. The expressions can include any
1584of the operators described in the next three sections. Note that the \fI@\fR
1585builtin command (q.v.) has its own separate syntax.
1586.SS "Logical, arithmetical and comparison operators"
1587These operators are similar to those of C and have the same precedence.
1588They include
1589.IP "" 4
1590|| && | ^ & == != =~ !~ <= >=
1591.br
1592< > << >> + \- * / % ! ~ ( )
1593.PP
1594Here the precedence increases to the right, `==' `!=' `=~' and `!~', `<='
1595`>=' `<' and `>', `<<' and `>>', `+' and `\-', `*' `/' and `%' being, in
1596groups, at the same level. The `==' `!=' `=~' and `!~' operators compare
1597their arguments as strings; all others operate on numbers. The operators
1598`=~' and `!~' are like `!=' and `==' except that the right hand side is a
1599glob-pattern (see \fBFilename substitution\fR) against which the left hand
1600operand is matched. This reduces the need for use of the \fIswitch\fR
1601builtin command in shell scripts when all that is really needed is
1602pattern matching.
1603.PP
1604Strings which begin with `0' are considered octal numbers. Null or
1605missing arguments are considered `0'. The results of all expressions are
1606strings, which represent decimal numbers. It is important to note that
1607no two components of an expression can appear in the same word; except
1608when adjacent to components of expressions which are syntactically
1609significant to the parser (`&' `|' `<' `>' `(' `)') they should be
1610surrounded by spaces.
1611.SS "Command exit status"
1612Commands can be executed in expressions and their exit status
1613returned by enclosing them in braces (`{}'). Remember that the braces should
1614be separated from the words of the command by spaces. Command executions
1615succeed, returning true, i.e., `1', if the command exits with status 0,
1616otherwise they fail, returning false, i.e., `0'. If more detailed status
1617information is required then the command should be executed outside of an
1618expression and the \fBstatus\fR shell variable examined.
1619.SS "File inquiry operators"
1620Some of these operators perform true/false tests on files and related
1621objects. They are of the form \fB\-\fIop file\fR, where \fIop\fR is one of
1622.PP
1623.PD 0
1624.RS +4
1625.TP 4
1626.B r
1627Read access
1628.TP 4
1629.B w
1630Write access
1631.TP 4
1632.B x
1633Execute access
1634.TP 4
1635.B X
1636Executable in the path or shell builtin, e.g., `\-X ls' and `\-X ls\-F' are
1637generally true, but `\-X /bin/ls' is not (+)
1638.TP 4
1639.B e
1640Existence
1641.TP 4
1642.B o
1643Ownership
1644.TP 4
1645.B z
1646Zero size
1647.TP 4
1648.B s
1649Non-zero size (+)
1650.TP 4
1651.B f
1652Plain file
1653.TP 4
1654.B d
1655Directory
1656.TP 4
1657.B l
1658Symbolic link (+) *
1659.TP 4
1660.B b
1661Block special file (+)
1662.TP 4
1663.B c
1664Character special file (+)
1665.TP 4
1666.B p
1667Named pipe (fifo) (+) *
1668.TP 4
1669.B S
1670Socket special file (+) *
1671.TP 4
1672.B u
1673Set-user-ID bit is set (+)
1674.TP 4
1675.B g
1676Set-group-ID bit is set (+)
1677.TP 4
1678.B k
1679Sticky bit is set (+)
1680.TP 4
1681.B t
1682\fIfile\fR (which must be a digit) is an open file descriptor
1683for a terminal device (+)
1684.TP 4
1685.B R
1686Has been migrated (convex only) (+)
1687.TP 4
1688.B L
1689Applies subsequent operators in a multiple-operator test to a symbolic link
1690rather than to the file to which the link points (+) *
1691.RE
1692.PD
1693.PP
1694\fIfile\fR is command and filename expanded and then tested to
1695see if it has the specified relationship to the real user. If \fIfile\fR
1696does not exist or is inaccessible or, for the operators indicated by `*',
1697if the specified file type does not exist on the current system,
1698then all enquiries return false, i.e., `0'.
1699.PP
1700These operators may be combined for conciseness: `\-\fIxy file\fR' is
1701equivalent to `\-\fIx file\fR && \-\fIy file\fR'. (+) For example, `\-fx' is true
1702(returns `1') for plain executable files, but not for directories.
1703.PP
1704\fBL\fR may be used in a multiple-operator test to apply subsequent operators
1705to a symbolic link rather than to the file to which the link points.
1706For example, `\-lLo' is true for links owned by the invoking user.
1707\fBLr\fR, \fBLw\fR and \fBLx\fR are always true for links and false for
1708non-links. \fBL\fR has a different meaning when it is the last operator
1709in a multiple-operator test; see below.
1710.PP
1711It is possible but not useful, and sometimes misleading, to combine operators
1712which expect \fIfile\fR to be a file with operators which do not,
1713(e.g., \fBX\fR and \fBt\fR). Following \fBL\fR with a non-file operator
1714can lead to particularly strange results.
1715.PP
1716Other operators return other information, i.e., not just `0' or `1'. (+)
1717They have the same format as before; \fIop\fR may be one of
1718.PP
1719.PD 0
1720.RS +4
1721.TP 8
1722.B A
1723Last file access time, as the number of seconds since the epoch
1724.TP 8
1725.B A:
1726Like \fBA\fR, but in timestamp format, e.g., `Fri May 14 16:36:10 1993'
1727.TP 8
1728.B M
1729Last file modification time
1730.TP 8
1731.B M:
1732Like \fBM\fR, but in timestamp format
1733.TP 8
1734.B C
1735Last inode modification time
1736.TP 8
1737.B C:
1738Like \fBC\fR, but in timestamp format
1739.TP 8
1740.B D
1741Device number
1742.TP 8
1743.B I
1744Inode number
1745.TP 8
1746.B F
1747Composite \fBf\fRile identifier, in the form \fIdevice\fR:\fIinode\fR
1748.TP 8
1749.B L
1750The name of the file pointed to by a symbolic link
1751.TP 8
1752.B N
1753Number of (hard) links
1754.TP 8
1755.B P
1756Permissions, in octal, without leading zero
1757.TP 8
1758.B P:
1759Like \fBP\fR, with leading zero
1760.TP 8
1761.B P\fImode
1762Equivalent to `\-P \fIfile\fR & \fImode\fR', e.g., `\-P22 \fIfile\fR' returns
1763`22' if \fIfile\fR is writable by group and other, `20' if by group only,
1764and `0' if by neither
1765.TP 8
1766.B P\fImode\fB:
1767Like \fBP\fImode\fB:\fR, with leading zero
1768.TP 8
1769.B U
1770Numeric userid
1771.TP 8
1772.B U:
1773Username, or the numeric userid if the username is unknown
1774.TP 8
1775.B G
1776Numeric groupid
1777.TP 8
1778.B G:
1779Groupname, or the numeric groupid if the groupname is unknown
1780.TP 8
1781.B Z
1782Size, in bytes
1783.RE
1784.PD
1785.PP
1786Only one of these operators may appear in a multiple-operator test, and it
1787must be the last. Note that \fBL\fR has a different meaning at the end of and
1788elsewhere in a multiple-operator test. Because `0' is a valid return value
1789for many of these operators, they do not return `0' when they fail: most
1790return `\-1', and \fBF\fR returns `:'.
1791.PP
1792If the shell is compiled with POSIX defined (see the \fBversion\fR shell
1793variable), the result of a file inquiry is based on the permission bits of
1794the file and not on the result of the \fIaccess\fR(2) system call.
1795For example, if one tests a file with \fB\-w\fR whose permissions would
1796ordinarily allow writing but which is on a file system mounted read-only,
1797the test will succeed in a POSIX shell but fail in a non-POSIX shell.
1798.PP
1799File inquiry operators can also be evaluated with the \fIfiletest\fR builtin
1800command (q.v.) (+).
1801.SS Jobs
1802The shell associates a \fIjob\fR with each pipeline. It keeps a table of
1803current jobs, printed by the \fIjobs\fR command, and assigns them small integer
1804numbers. When a job is started asynchronously with `&', the shell prints a
1805line which looks like
1806.IP "" 4
1807[1] 1234
1808.PP
1809indicating that the job which was started asynchronously was job number 1 and
1810had one (top-level) process, whose process id was 1234.
1811.PP
1812If you are running a job and wish to do something else you may hit the suspend
1813key (usually `^Z'),
1814which sends a STOP signal to the current job. The shell will then normally
1815indicate that the job has been `Suspended' and print another prompt.
1816If the \fBlistjobs\fR shell variable is set, all jobs will be listed
1817like the \fIjobs\fR builtin command; if it is set to `long' the listing will
1818be in long format, like `jobs \-l'.
1819You can then manipulate the state of the suspended job.
1820You can put it in the
1821``background'' with the \fIbg\fR command or run some other commands and
1822eventually bring the job back into the ``foreground'' with \fIfg\fR.
1823(See also the \fIrun-fg-editor\fR editor command.)
1824A `^Z' takes effect immediately and is like an interrupt
1825in that pending output and unread input are discarded when it is typed.
1826The \fIwait\fR builtin command causes the shell to wait for all background
1827jobs to complete.
1828.PP
1829The `^]' key sends a delayed suspend signal, which does not generate a STOP
1830signal until a program attempts to \fIread\fR(2) it, to the current job.
1831This can usefully be typed ahead when you have prepared some commands for a
1832job which you wish to stop after it has read them.
1833The `^Y' key performs this function in \fIcsh\fR(1); in \fItcsh\fR,
1834`^Y' is an editing command. (+)
1835.PP
1836A job being run in the background stops if it tries to read from the
1837terminal. Background jobs are normally allowed to produce output, but this can
1838be disabled by giving the command `stty tostop'. If you set this tty option,
1839then background jobs will stop when they try to produce output like they do
1840when they try to read input.
1841.PP
1842There are several ways to refer to jobs in the shell. The character `%'
1843introduces a job name. If you wish to refer to job number 1, you can name it
1844as `%1'. Just naming a job brings it to the foreground; thus `%1' is a synonym
1845for `fg %1', bringing job 1 back into the foreground. Similarly, saying `%1 &'
1846resumes job 1 in the background, just like `bg %1'. A job can also be named
1847by an unambiguous prefix of the string typed in to start it: `%ex' would
1848normally restart a suspended \fIex\fR(1) job, if there were only one suspended
1849job whose name began with the string `ex'. It is also possible to say
1850`%?\fIstring\fR' to specify a job whose text contains \fIstring\fR, if there
1851is only one such job.
1852.PP
1853The shell maintains a notion of the current and previous jobs. In output
1854pertaining to jobs, the current job is marked with a `+' and the previous job
1855with a `\-'. The abbreviations `%+', `%', and (by analogy with the syntax of
1856the \fIhistory\fR mechanism) `%%' all refer to the current job, and `%\-' refers
1857to the previous job.
1858.PP
1859The job control mechanism requires that the \fIstty\fR(1) option `new' be set
1860on some systems. It is an artifact from a `new' implementation of the tty
1861driver which allows generation of interrupt characters from the keyboard to
1862tell jobs to stop. See \fIstty\fR(1) and the \fIsetty\fR builtin command for
1863details on setting options in the new tty driver.
1864.SS "Status reporting"
1865The shell learns immediately whenever a process changes state. It normally
1866informs you whenever a job becomes blocked so that no further progress is
1867possible, but only right before it prints a prompt. This is done so that it
1868does not otherwise disturb your work. If, however, you set the shell variable
1869\fBnotify\fR, the shell will notify you immediately of changes of status in
1870background jobs. There is also a shell command \fInotify\fR which marks a
1871single process so that its status changes will be immediately reported. By
1872default \fInotify\fR marks the current process; simply say `notify' after
1873starting a background job to mark it.
1874.PP
1875When you try to leave the shell while jobs are stopped, you will be
1876warned that `You have stopped jobs.' You may use the \fIjobs\fR command to see
1877what they are. If you do this or immediately try to exit again, the shell will
1878not warn you a second time, and the suspended jobs will be terminated.
1879.SS "Automatic, periodic and timed events (+)"
1880There are various ways to run commands and take other actions automatically
1881at various times in the ``life cycle'' of the shell. They are summarized here,
1882and described in detail under the appropriate \fBBuiltin commands\fR,
1883\fBSpecial shell variables\fR and \fBSpecial aliases\fR.
1884.PP
1885The \fIsched\fR builtin command puts commands in a scheduled-event list,
1886to be executed by the shell at a given time.
1887.PP
|
1885The \fIbeepcmd\fR, \fIcwdcmd\fR, \fIperiodic\fR, \fIprecmd\fR, and \fIpostcmd\fR
| 1888The \fIbeepcmd\fR, \fIcwdcmd\fR, \fIperiodic\fR, \fIprecmd\fR, \fIpostcmd\fR,
1889and \fIjobcmd\fR
|
1886\fBSpecial aliases\fR can be set, respectively, to execute commands when the shell wants
1887to ring the bell, when the working directory changes, every \fBtperiod\fR
| 1890\fBSpecial aliases\fR can be set, respectively, to execute commands when the shell wants
1891to ring the bell, when the working directory changes, every \fBtperiod\fR
|
1888minutes, before each prompt, and before each command gets executed.
| 1892minutes, before each prompt, before each command gets executed, after each
1893command gets executed, and when a job is started or is brought into the
1894foreground.
|
1889.PP
1890The \fBautologout\fR shell variable can be set to log out or lock the shell
1891after a given number of minutes of inactivity.
1892.PP
1893The \fBmail\fR shell variable can be set to check for new mail periodically.
1894.PP
1895The \fBprintexitvalue\fR shell variable can be set to print the exit status
1896of commands which exit with a status other than zero.
1897.PP
1898The \fBrmstar\fR shell variable can be set to ask the user, when `rm *' is
1899typed, if that is really what was meant.
1900.PP
1901The \fBtime\fR shell variable can be set to execute the \fItime\fR builtin
1902command after the completion of any process that takes more than a given
1903number of CPU seconds.
1904.PP
1905The \fBwatch\fR and \fBwho\fR shell variables can be set to report when
1906selected users log in or out, and the \fIlog\fR builtin command reports
1907on those users at any time.
1908.SS "Native Language System support (+)"
1909The shell is eight bit clean
1910(if so compiled; see the \fBversion\fR shell variable)
1911and thus supports character sets needing this capability.
1912NLS support differs depending on whether or not
1913the shell was compiled to use the system's NLS (again, see \fBversion\fR).
1914In either case, 7-bit ASCII is the default for character classification
1915(e.g., which characters are printable) and sorting,
1916and changing the \fBLANG\fR or \fBLC_CTYPE\fR environment variables
1917causes a check for possible changes in these respects.
1918.PP
1919When using the system's NLS, the \fIsetlocale\fR(3) function is called
1920to determine appropriate character classification and sorting.
1921This function typically examines the \fBLANG\fR and \fBLC_CTYPE\fR
1922environment variables; refer to the system documentation for further details.
1923When not using the system's NLS, the shell simulates it by assuming that the
1924ISO 8859-1 character set is used
1925whenever either of the \fBLANG\fR and \fBLC_CTYPE\fR variables are set, regardless of
1926their values. Sorting is not affected for the simulated NLS.
1927.PP
1928In addition, with both real and simulated NLS, all printable
1929characters in the range \e200\-\e377, i.e., those that have
1930M-\fIchar\fR bindings, are automatically rebound to \fIself-insert-command\fR.
1931The corresponding binding for the escape-\fIchar\fR sequence, if any, is
1932left alone.
1933These characters are not rebound if the \fBNOREBIND\fR environment variable
1934is set. This may be useful for the simulated NLS or a primitive real NLS
1935which assumes full ISO 8859-1. Otherwise, all M-\fIchar\fR bindings in the
1936range \e240\-\e377 are effectively undone.
1937Explicitly rebinding the relevant keys with \fIbindkey\fR
1938is of course still possible.
1939.PP
1940Unknown characters (i.e., those that are neither printable nor control
1941characters) are printed in the format \ennn.
1942If the tty is not in 8 bit mode, other 8 bit characters are printed by
1943converting them to ASCII and using standout mode. The shell
1944never changes the 7/8 bit mode of the tty and tracks user-initiated
1945changes of 7/8 bit mode. NLS users (or, for that matter, those who want to
1946use a meta key) may need to explicitly set
1947the tty in 8 bit mode through the appropriate \fIstty\fR(1)
1948command in, e.g., the \fI~/.login\fR file.
1949.SS "OS variant support (+)"
1950A number of new builtin commands are provided to support features in
1951particular operating systems. All are described in detail in the
1952\fBBuiltin commands\fR section.
1953.PP
1954On systems that support TCF (aix-ibm370, aix-ps2),
1955\fIgetspath\fR and \fIsetspath\fR get and set the system execution path,
1956\fIgetxvers\fR and \fIsetxvers\fR get and set the experimental version prefix
1957and \fImigrate\fR migrates processes between sites. The \fIjobs\fR builtin
1958prints the site on which each job is executing.
1959.PP
1960Under Domain/OS, \fIinlib\fR adds shared libraries to the current environment,
1961\fIrootnode\fR changes the rootnode and \fIver\fR changes the systype.
1962.PP
1963Under Mach, \fIsetpath\fR is equivalent to Mach's \fIsetpath\fR(1).
1964.PP
1965Under Masscomp/RTU and Harris CX/UX, \fIuniverse\fR sets the universe.
1966.PP
1967Under Harris CX/UX, \fIucb\fR or \fIatt\fR runs a command under the specified
1968universe.
1969.PP
1970Under Convex/OS, \fIwarp\fR prints or sets the universe.
1971.PP
1972The \fBVENDOR\fR, \fBOSTYPE\fR and \fBMACHTYPE\fR environment variables
1973indicate respectively the vendor, operating system and machine type
1974(microprocessor class or machine model) of the
1975system on which the shell thinks it is running.
1976These are particularly useful when sharing one's home directory between several
1977types of machines; one can, for example,
1978.IP "" 4
1979set path = (~/bin.$MACHTYPE /usr/ucb /bin /usr/bin .)
1980.PP
1981in one's \fI~/.login\fR and put executables compiled for each machine in the
1982appropriate directory.
1983.PP
1984The \fBversion\fR shell
1985variable indicates what options were chosen when the shell was compiled.
1986.PP
1987Note also the \fInewgrp\fR builtin, the \fBafsuser\fR and
1988\fBecho_style\fR shell variables and the system-dependent locations of
1989the shell's input files (see \fBFILES\fR).
1990.SS "Signal handling"
1991Login shells ignore interrupts when reading the file \fI~/.logout\fR.
1992The shell ignores quit signals unless started with \fB\-q\fR.
1993Login shells catch the terminate signal, but non-login shells inherit the
1994terminate behavior from their parents.
1995Other signals have the values which the shell inherited from its parent.
1996.PP
1997In shell scripts, the shell's handling of interrupt and terminate signals
1998can be controlled with \fIonintr\fR, and its handling of hangups can be
1999controlled with \fIhup\fR and \fInohup\fR.
2000.PP
2001The shell exits on a hangup (see also the \fBlogout\fR shell variable). By
2002default, the shell's children do too, but the shell does not send them a
2003hangup when it exits. \fIhup\fR arranges for the shell to send a hangup to
2004a child when it exits, and \fInohup\fR sets a child to ignore hangups.
2005.SS "Terminal management (+)"
2006The shell uses three different sets of terminal (``tty'') modes:
2007`edit', used when editing, `quote', used when quoting literal characters,
2008and `execute', used when executing commands.
2009The shell holds some settings in each mode constant, so commands which leave
2010the tty in a confused state do not interfere with the shell.
2011The shell also matches changes in the speed and padding of the tty.
2012The list of tty modes that are kept constant
2013can be examined and modified with the \fIsetty\fR builtin.
2014Note that although the editor uses CBREAK mode (or its equivalent),
2015it takes typed-ahead characters anyway.
2016.PP
2017The \fIechotc\fR, \fIsettc\fR and \fItelltc\fR commands can be used to
2018manipulate and debug terminal capabilities from the command line.
2019.PP
2020On systems that support SIGWINCH or SIGWINDOW, the shell
2021adapts to window resizing automatically and adjusts the environment
2022variables \fBLINES\fR and \fBCOLUMNS\fR if set. If the environment
2023variable \fBTERMCAP\fR contains li# and co# fields, the shell adjusts
2024them to reflect the new window size.
2025.SH REFERENCE
2026The next sections of this manual describe all of the available
2027\fBBuiltin commands\fR, \fBSpecial aliases\fR and
2028\fBSpecial shell variables\fR.
2029.SS "Builtin commands"
2030.TP 8
2031.B %\fIjob
2032A synonym for the \fIfg\fR builtin command.
2033.TP 8
2034.B %\fIjob \fB&
2035A synonym for the \fIbg\fR builtin command.
2036.TP 8
2037.B :
2038Does nothing, successfully.
2039.PP
2040.B @
2041.br
2042.B @ \fIname\fB = \fIexpr
2043.br
2044.B @ \fIname\fR[\fIindex\fR]\fB = \fIexpr
2045.br
2046.B @ \fIname\fB++\fR|\fB--
2047.PD 0
2048.TP 8
2049.B @ \fIname\fR[\fIindex\fR]\fB++\fR|\fB--
2050The first form prints the values of all shell variables.
2051.PD
2052.RS +8
2053.PP
2054The second form assigns the value of \fIexpr\fR to \fIname\fR.
2055The third form assigns the value of \fIexpr\fR to the \fIindex\fR'th
2056component of \fIname\fR; both \fIname\fR and its \fIindex\fR'th component
2057must already exist.
2058.PP
2059\fIexpr\fR may contain the operators `*', `+', etc., as in C.
2060If \fIexpr\fR contains `<', `>', `&' or `' then at least that part of
2061\fIexpr\fR must be placed within `()'.
2062Note that the syntax of \fIexpr\fR has nothing to do with that described
2063under \fBExpressions\fR.
2064.PP
2065The fourth and fifth forms increment (`++') or decrement (`\-\-') \fIname\fR
2066or its \fIindex\fR'th component.
2067.PP
2068The space between `@' and \fIname\fR is required. The spaces between
2069\fIname\fR and `=' and between `=' and \fIexpr\fR are optional. Components of
2070\fIexpr\fR must be separated by spaces.
2071.RE
2072.PD
2073.TP 8
2074.B alias \fR[\fIname \fR[\fIwordlist\fR]]
2075Without arguments, prints all aliases.
2076With \fIname\fR, prints the alias for name.
2077With \fIname\fR and \fIwordlist\fR, assigns
2078\fIwordlist\fR as the alias of \fIname\fR.
2079\fIwordlist\fR is command and filename substituted.
2080\fIname\fR may not be `alias' or `unalias'.
2081See also the \fIunalias\fR builtin command.
2082.ig \" Obsolete tcsh command
2083.TP 8
2084.B aliases \fR[\fIfile\fR] (+)
2085Without arguments, prints all aliases.
2086With \fIfile\fR, loads a list of aliases from \fIfile\fR, one per line.
2087Retained for only downward compatibility.
2088..
2089.TP 8
2090.B alloc
2091Shows the amount of dynamic memory acquired, broken down into used and free
2092memory. With an argument shows the number of free and used blocks in each size
2093category. The categories start at size 8 and double at each step. This
2094command's output may vary across system types, because systems other than the VAX
2095may use a different memory allocator.
2096.TP 8
2097.B bg \fR[\fB%\fIjob\fR ...]
2098Puts the specified jobs (or, without arguments, the current job)
2099into the background, continuing each if it is stopped.
2100\fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
2101under \fBJobs\fR.
2102.ig \" Obsolete tcsh command
2103.TP 8
2104.B bind \fR[\fBdefaults\fR|\fBemacs\fR|\fBvi\fR|\fIkey\fR|\fIkey command\fR] (+)
2105An older version of \fIbindkey\fR, retained for only downward compatibility.
2106Without arguments, lists all bound keys and the editor command to which each is bound.
2107`bind defaults', `bind emacs' and `bind vi' are equivalent to
2108`bindkey \-d', `bindkey \-e' and `bindkey \-v'.
2109With \fIkey\fR, lists the editor command to which \fIkey\fR is bound.
2110With \fIkey\fR and \fIcommand\fR, binds the editor command \fIcommand\fR to \fIkey\fR.
2111.IP "" 8
2112\fIkey\fR may be a literal character,
2113a control character written ^\fIcharacter\fR (e.g., `^A'),
2114a meta character written M-\fIcharacter\fR (e.g., `M-A')
2115or a function key written F-\fIstring\fR (e.g., `F-foo').
2116For the function key form to work, the function key prefix must be
2117bound to \fIsequence-lead-in\fR and \fIstring\fR must not contain that prefix.
2118..
2119.PP
2120.B bindkey \fR[\fB\-l\fR|\fB\-d\fR|\fB\-e\fR|\fB\-v\fR|\fB\-u\fR] (+)
2121.br
2122\fBbindkey \fR[\fB\-a\fR] [\fB\-b\fR] [\fB\-k\fR] [\fB\-r\fR] [\fB\-\-\fR] \fIkey \fR(+)
2123.PD 0
2124.TP 8
2125\fBbindkey \fR[\fB\-a\fR] [\fB\-b\fR] [\fB\-k\fR] [\fB\-c\fR|\fB\-s\fR] [\fB\-\-\fR] \fIkey command \fR(+)
2126.\" .B macro can't take too many words, so I used \fB in the previous tags
2127Without options, the first form lists all bound keys and the editor command to which each is bound,
2128the second form lists the editor command to which \fIkey\fR is bound and
2129the third form binds the editor command \fIcommand\fR to \fIkey\fR.
2130Options include:
2131.PD
2132.PP
2133.PD 0
2134.RS +8
2135.TP 4
2136.B \-l
2137Lists all editor commands and a short description of each.
2138.TP 4
2139.B \-d
2140Binds all keys to the standard bindings for the default editor.
2141.TP 4
2142.B \-e
2143Binds all keys to the standard GNU Emacs-like bindings.
2144.TP 4
2145.B \-v
2146Binds all keys to the standard \fIvi\fR(1)-like bindings.
2147.TP 4
2148.B \-a
2149Lists or changes key-bindings in the alternative key map.
2150This is the key map used in \fIvi\fR command mode.
2151.TP 4
2152.B \-b
2153\fIkey\fR is interpreted as
2154a control character written ^\fIcharacter\fR (e.g., `^A') or
2155C-\fIcharacter\fR (e.g., `C-A'),
2156a meta character written M-\fIcharacter\fR (e.g., `M-A'),
2157a function key written F-\fIstring\fR (e.g., `F-string'),
2158or an extended prefix key written X-\fIcharacter\fR (e.g., `X-A').
2159.TP 4
2160.B \-k
2161\fIkey\fR is interpreted as a symbolic arrow key name, which may be one of
2162`down', `up', `left' or `right'.
2163.TP 4
2164.B \-r
2165Removes \fIkey\fR's binding.
2166Be careful: `bindkey \-r' does \fInot\fR bind \fIkey\fR to
2167\fIself-insert-command\fR (q.v.), it unbinds \fIkey\fR completely.
2168.TP 4
2169.B \-c
2170\fIcommand\fR is interpreted as a builtin or external command instead of an
2171editor command.
2172.TP 4
2173.B \-s
2174\fIcommand\fR is taken as a literal string and treated as terminal input
2175when \fIkey\fR is typed. Bound keys in \fIcommand\fR are themselves
2176reinterpreted, and this continues for ten levels of interpretation.
2177.TP 4
2178.B \-\-
2179Forces a break from option processing, so the next word is taken as \fIkey\fR
2180even if it begins with '\-'.
2181.TP 4
2182.B \-u \fR(or any invalid option)
2183Prints a usage message.
2184.PD
2185.PP
2186\fIkey\fR may be a single character or a string.
2187If a command is bound to a string, the first character of the string is bound to
2188\fIsequence-lead-in\fR and the entire string is bound to the command.
2189.PP
2190Control characters in \fIkey\fR can be literal (they can be typed by preceding
2191them with the editor command \fIquoted-insert\fR, normally bound to `^V') or
2192written caret-character style, e.g., `^A'. Delete is written `^?'
2193(caret-question mark). \fIkey\fR and \fIcommand\fR can contain backslashed
2194escape sequences (in the style of System V \fIecho\fR(1)) as follows:
2195.RS +4
2196.TP 8
2197.PD 0
2198.B \ea
2199Bell
2200.TP 8
2201.B \eb
2202Backspace
2203.TP 8
2204.B \ee
2205Escape
2206.TP 8
2207.B \ef
2208Form feed
2209.TP 8
2210.B \en
2211Newline
2212.TP 8
2213.B \er
2214Carriage return
2215.TP 8
2216.B \et
2217Horizontal tab
2218.TP 8
2219.B \ev
2220Vertical tab
2221.TP 8
2222.B \e\fInnn
2223The ASCII character corresponding to the octal number \fInnn\fR
2224.PD
2225.RE
2226.PP
2227`\e' nullifies the special meaning of the following character, if it has
2228any, notably `\\' and `^'.
2229.RE
2230.TP 8
2231.B break
2232Causes execution to resume after the \fIend\fR of the nearest
2233enclosing \fIforeach\fR or \fIwhile\fR. The remaining commands on the
2234current line are executed. Multi-level breaks are thus
2235possible by writing them all on one line.
2236.TP 8
2237.B breaksw
2238Causes a break from a \fIswitch\fR, resuming after the \fIendsw\fR.
2239.TP 8
2240.B builtins \fR(+)
2241Prints the names of all builtin commands.
2242.TP 8
2243.B bye \fR(+)
2244A synonym for the \fIlogout\fR builtin command.
2245Available only if the shell was so compiled;
2246see the \fBversion\fR shell variable.
2247.TP 8
2248.B case \fIlabel\fB:
2249A label in a \fIswitch\fR statement as discussed below.
2250.TP 8
2251.B cd \fR[\fB\-p\fR] [\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR] [\fIname\fR]
2252If a directory \fIname\fR is given, changes the shell's working directory
2253to \fIname\fR. If not, changes to \fBhome\fR.
2254If \fIname\fR is `\-' it is interpreted as the previous working directory
2255(see \fBOther substitutions\fR). (+)
2256If \fIname\fR is not a subdirectory of the current directory
2257(and does not begin with `/', `./' or `../'), each component of the variable
2258\fBcdpath\fR is checked to see if it has a subdirectory \fIname\fR. Finally, if
2259all else fails but \fIname\fR is a shell variable whose value
2260begins with `/', then this is tried to see if it is a directory.
2261.RS +8
2262.PP
2263With \fB\-p\fR, prints the final directory stack, just like \fIdirs\fR.
2264The \fB\-l\fR, \fB\-n\fR and \fB\-v\fR flags have the same effect on \fIcd\fR
2265as on \fIdirs\fR, and they imply \fB\-p\fR. (+)
2266.PP
2267See also the \fBimplicitcd\fR shell variable.
2268.RE
2269.TP 8
2270.B chdir
2271A synonym for the \fIcd\fR builtin command.
2272.TP 8
2273.B complete \fR[\fIcommand\fR [\fIword\fB/\fIpattern\fB/\fIlist\fR[\fB:\fIselect\fR]\fB/\fR[[\fIsuffix\fR]\fB/\fR] ...]] (+)
2274Without arguments, lists all completions.
2275With \fIcommand\fR, lists completions for \fIcommand\fR.
2276With \fIcommand\fR and \fIword\fR etc., defines completions.
2277.RS +8
2278.PP
2279\fIcommand\fR may be a full command name or a glob-pattern
2280(see \fBFilename substitution\fR). It can begin with `\-' to indicate that
2281completion should be used only when \fIcommand\fR is ambiguous.
2282.PP
2283\fIword\fR specifies which word relative to the current word
2284is to be completed, and may be one of the following:
2285.PP
2286.PD 0
2287.RS +4
2288.TP 4
2289.B c
2290Current-word completion.
2291\fIpattern\fR is a glob-pattern which must match the beginning of the current word on
2292the command line. \fIpattern\fR is ignored when completing the current word.
2293.TP 4
2294.B C
2295Like \fBc\fR, but includes \fIpattern\fR when completing the current word.
2296.TP 4
2297.B n
2298Next-word completion.
2299\fIpattern\fR is a glob-pattern which must match the beginning of the previous word on
2300the command line.
2301.TP 4
2302.B N
2303Like \fBn\fR, but must match the beginning of the word two before the current word.
2304.TP 4
2305.B p
2306Position-dependent completion.
2307\fIpattern\fR is a numeric range, with the same syntax used to index shell
2308variables, which must include the current word.
2309.PD
2310.RE
2311.ig \" No longer true in 6.05.04
2312.PP
2313When \fIpattern\fR is a glob-pattern (for \fBc\fR, \fBC\fR, \fBn\fR and
2314\fBN\fR-type completion), a \fIpattern\fR of `*' does not match an empty
2315word.
2316..
2317.PP
2318\fIlist\fR, the list of possible completions, may be one of the following:
2319.PP
2320.PD 0
2321.RS +4
2322.TP 8
2323.B a
2324Aliases
2325.TP 8
2326.B b
2327Bindings (editor commands)
2328.TP 8
2329.B c
2330Commands (builtin or external commands)
2331.TP 8
2332.B C
2333External commands which begin with the supplied path prefix
2334.TP 8
2335.B d
2336Directories
2337.TP 8
2338.B D
2339Directories which begin with the supplied path prefix
2340.TP 8
2341.B e
2342Environment variables
2343.TP 8
2344.B f
2345Filenames
2346.TP 8
2347.B F
2348Filenames which begin with the supplied path prefix
2349.TP 8
2350.B g
2351Groupnames
2352.TP 8
2353.B j
2354Jobs
2355.TP 8
2356.B l
2357Limits
2358.TP 8
2359.B n
2360Nothing
2361.TP 8
2362.B s
2363Shell variables
2364.TP 8
2365.B S
2366Signals
2367.TP 8
2368.B t
2369Plain (``text'') files
2370.TP 8
2371.B T
2372Plain (``text'') files which begin with the supplied path prefix
2373.TP 8
2374.B v
2375Any variables
2376.TP 8
2377.B u
2378Usernames
2379.TP 8
2380.B x
2381Like \fBn\fR, but prints \fIselect\fR when \fIlist-choices\fR is used.
2382.TP 8
2383.B X
2384Completions
2385.TP 8
2386$\fIvar\fR
2387Words from the variable \fIvar\fR
2388.TP 8
2389(...)
2390Words from the given list
2391.TP 8
2392`...`
2393Words from the output of command
2394.PD
2395.RE
2396.PP
2397\fIselect\fR is an optional glob-pattern.
2398If given, words from only \fIlist\fR that match \fIselect\fR are considered
2399and the \fBfignore\fR shell variable is ignored.
2400The last three types of completion may not have a \fIselect\fR
2401pattern, and \fBx\fR uses \fIselect\fR as an explanatory message when
2402the \fIlist-choices\fR editor command is used.
2403.PP
2404\fIsuffix\fR is a single character to be appended to a successful
2405completion. If null, no character is appended. If omitted (in which
2406case the fourth delimiter can also be omitted), a slash is appended to
2407directories and a space to other words.
2408.PP
2409Now for some examples. Some commands take only directories as arguments,
2410so there's no point completing plain files.
2411.IP "" 4
2412> complete cd 'p/1/d/'
2413.PP
2414completes only the first word following `cd' (`p/1') with a directory.
2415\fBp\fR-type completion can also be used to narrow down command completion:
2416.IP "" 4
2417> co[^D]
2418.br
2419complete compress
2420.br
2421> complete \-co* 'p/0/(compress)/'
2422.br
2423> co[^D]
2424.br
2425> compress
2426.PP
2427This completion completes commands (words in position 0, `p/0')
2428which begin with `co' (thus matching `co*') to `compress' (the only
2429word in the list).
2430The leading `\-' indicates that this completion is to be used with only
2431ambiguous commands.
2432.IP "" 4
2433> complete find 'n/\-user/u/'
2434.PP
2435is an example of \fBn\fR-type completion. Any word following `find' and
2436immediately following `\-user' is completed from the list of users.
2437.IP "" 4
2438> complete cc 'c/\-I/d/'
2439.PP
2440demonstrates \fBc\fR-type completion. Any word following `cc' and beginning
2441with `\-I' is completed as a directory. `\-I' is not taken as part of the
2442directory because we used lowercase \fBc\fR.
2443.PP
2444Different \fIlist\fRs are useful with different commands.
2445.IP "" 4
2446> complete alias 'p/1/a/'
2447.br
2448> complete man 'p/*/c/'
2449.br
2450> complete set 'p/1/s/'
2451.br
2452> complete true 'p/1/x:Truth has no options./'
2453.PP
2454These complete words following `alias' with aliases, `man' with commands,
2455and `set' with shell variables.
2456`true' doesn't have any options, so \fBx\fR does nothing when completion
2457is attempted and prints `Truth has no options.' when completion choices are listed.
2458.PP
2459.ig \" Changed in 6.05.04
2460The \fIman\fR example, and several other examples below, use
2461\fBp\fR-type completion, rather than \fBC\fR- or \fBn\fR-type, so that
2462`*' will match an empty word.
2463..
2464Note that the \fIman\fR example, and several other examples below, could
2465just as well have used 'c/*' or 'n/*' as 'p/*'.
2466.PP
2467Words can be completed from a variable evaluated at completion time,
2468.IP "" 4
2469> complete ftp 'p/1/$hostnames/'
2470.br
2471> set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu)
2472.br
2473> ftp [^D]
2474.br
2475rtfm.mit.edu tesla.ee.cornell.edu
2476.br
2477> ftp [^C]
2478.br
2479> set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net)
2480.br
2481> ftp [^D]
2482.br
2483rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net
2484.PP
2485or from a command run at completion time:
2486.IP "" 4
2487> complete kill 'p/*/`ps | awk \\{print\\ \\$1\\}`/'
2488.br
2489> kill \-9 [^D]
2490.br
249123113 23377 23380 23406 23429 23529 23530 PID
2492.PP
2493Note that the \fIcomplete\fR command does not itself quote its arguments,
2494so the braces, space and `$' in `{print $1}' must be quoted explicitly.
2495.PP
2496One command can have multiple completions:
2497.IP "" 4
2498> complete dbx 'p/2/(core)/' 'p/*/c/'
2499.PP
2500completes the second argument to `dbx' with the word `core' and all other
2501arguments with commands. Note that the positional completion is specified
2502before the next-word completion.
2503Because completions are evaluated from left to right, if
2504the next-word completion were specified first it would always match
2505and the positional completion would never be executed. This is a
2506common mistake when defining a completion.
2507.PP
2508The \fIselect\fR pattern is useful when a command takes files with only
2509particular forms as arguments. For example,
2510.IP "" 4
2511> complete cc 'p/*/f:*.[cao]/'
2512.PP
2513completes `cc' arguments to files ending in only `.c', `.a', or `.o'.
2514\fIselect\fR can also exclude files, using negation of a glob-pattern as
2515described under \fBFilename substitution\fR. One might use
2516.IP "" 4
2517> complete rm 'p/*/f:^*.{c,h,cc,C,tex,1,man,l,y}/'
2518.PP
2519to exclude precious source code from `rm' completion. Of course, one
2520could still type excluded names manually or override the completion
2521mechanism using the \fIcomplete-word-raw\fR or \fIlist-choices-raw\fR
2522editor commands (q.v.).
2523.PP
2524The `C', `D', `F' and `T' \fIlist\fRs are like `c', `d', `f' and `t'
2525respectively, but they use the \fIselect\fR argument in a different way: to
2526restrict completion to files beginning with a particular path prefix. For
2527example, the Elm mail program uses `=' as an abbreviation for one's mail
2528directory. One might use
2529.IP "" 4
2530> complete elm c@=@F:$HOME/Mail/@
2531.PP
2532to complete `elm \-f =' as if it were `elm \-f ~/Mail/'. Note that we used `@'
2533instead of `/' to avoid confusion with the \fIselect\fR argument, and we used
2534`$HOME' instead of `~' because home directory substitution works at only the
2535beginning of a word.
2536.PP
2537\fIsuffix\fR is used to add a nonstandard suffix
2538(not space or `/' for directories) to completed words.
2539.IP "" 4
2540> complete finger 'c/*@/$hostnames/' 'p/1/u/@'
2541.PP
2542completes arguments to `finger' from the list of users, appends an `@',
2543and then completes after the `@' from the `hostnames' variable. Note
2544again the order in which the completions are specified.
2545.PP
2546Finally, here's a complex example for inspiration:
2547.IP "" 4
2548> complete find \\
2549.br
2550\'n/\-name/f/' 'n/\-newer/f/' 'n/\-{,n}cpio/f/' \e
2551.br
2552\'n/\-exec/c/' 'n/\-ok/c/' 'n/\-user/u/' \e
2553.br
2554\'n/\-group/g/' 'n/\-fstype/(nfs 4.2)/' \e
2555.br
2556\'n/\-type/(b c d f l p s)/' \e
2557.br
2558\'c/\-/(name newer cpio ncpio exec ok user \e
2559.br
2560group fstype type atime ctime depth inum \e
2561.br
2562ls mtime nogroup nouser perm print prune \e
2563.br
2564size xdev)/' \e
2565.br
2566\'p/*/d/'
2567.PP
2568This completes words following `\-name', `\-newer', `\-cpio' or `ncpio'
2569(note the pattern which matches both) to files,
2570words following `\-exec' or `\-ok' to commands, words following `user'
2571and `group' to users and groups respectively
2572and words following `\-fstype' or `\-type' to members of the
2573given lists. It also completes the switches themselves from the given list
2574(note the use of \fBc\fR-type completion)
2575and completes anything not otherwise completed to a directory. Whew.
2576.PP
2577Remember that programmed completions are ignored if the word being completed
2578is a tilde substitution (beginning with `~') or a variable (beginning with `$').
2579\fIcomplete\fR is an experimental feature, and the syntax may change
2580in future versions of the shell.
2581See also the \fIuncomplete\fR builtin command.
2582.RE
2583.TP 8
2584.B continue
2585Continues execution of the nearest enclosing \fIwhile\fR or \fIforeach\fR.
2586The rest of the commands on the current line are executed.
2587.TP 8
2588.B default:
2589Labels the default case in a \fIswitch\fR statement.
2590It should come after all \fIcase\fR labels.
2591.PP
2592.B dirs \fR[\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR]
2593.br
2594.B dirs \-S\fR|\fB\-L \fR[\fIfilename\fR] (+)
2595.PD 0
2596.TP 8
2597.B dirs \-c \fR(+)
2598The first form prints the directory stack. The top of the stack is at the
2599left and the first directory in the stack is the current directory.
2600With \fB\-l\fR, `~' or `~\fIname\fP' in the output is expanded explicitly
2601to \fBhome\fR or the pathname of the home directory for user \fIname\fP. (+)
2602With \fB\-n\fR, entries are wrapped before they reach the edge of the screen. (+)
2603With \fB\-v\fR, entries are printed one per line, preceded by their stack positions. (+)
2604If more than one of \fB\-n\fR or \fB\-v\fR is given, \fB\-v\fR takes precedence.
2605\fB\-p\fR is accepted but does nothing.
2606.PD
2607.RS +8
2608.PP
2609With \fB\-S\fR, the second form saves the directory stack to \fIfilename\fR
2610as a series of \fIcd\fR and \fIpushd\fR commands.
2611With \fB\-L\fR, the shell sources \fIfilename\fR, which is presumably
2612a directory stack file saved by the \fB\-S\fR option or the \fBsavedirs\fR
2613mechanism.
2614In either case, \fBdirsfile\fR is used if \fIfilename\fR is not given and
2615\fI~/.cshdirs\fR is used if \fBdirsfile\fR is unset.
2616.PP
2617Note that login shells do the equivalent of `dirs \-L' on startup
2618and, if \fBsavedirs\fR is set, `dirs \-S' before exiting.
2619Because only \fI~/.tcshrc\fR is normally sourced before \fI~/.cshdirs\fR,
2620\fBdirsfile\fR should be set in \fI~/.tcshrc\fR rather than \fI~/.login\fR.
2621.PP
2622The last form clears the directory stack.
2623.RE
2624.TP 8
2625.B echo \fR[\fB\-n\fR] \fIword\fR ...
2626Writes each \fIword\fR to the shell's standard
2627output, separated by spaces and terminated with a newline.
2628The \fBecho_style\fR shell variable may be set to emulate (or not) the flags and escape
2629sequences of the BSD and/or System V versions of \fIecho\fR; see \fIecho\fR(1).
2630.TP 8
2631.B echotc \fR[\fB\-sv\fR] \fIarg\fR ... (+)
2632Exercises the terminal capabilities (see \fItermcap\fR(5)) in \fIargs\fR.
2633For example, 'echotc home' sends the cursor to the home position,
2634\&'echotc cm 3 10' sends it to column 3 and row 10, and
2635\&'echotc ts 0; echo "This is a test."; echotc fs' prints "This is a test."
2636in the status line.
2637.RS +8
2638.PP
2639If \fIarg\fR is 'baud', 'cols', 'lines', 'meta' or 'tabs', prints the
2640value of that capability ("yes" or "no" indicating that the terminal does
2641or does not have that capability). One might use this to make the output
2642from a shell script less verbose on slow terminals, or limit command
2643output to the number of lines on the screen:
2644.IP "" 4
2645> set history=`echotc lines`
2646.br
2647> @ history\-\-
2648.PP
2649Termcap strings may contain wildcards which will not echo correctly.
2650One should use double quotes when setting a shell variable to a terminal
2651capability string, as in the following example that places the date in
2652the status line:
2653.IP "" 4
2654> set tosl="`echotc ts 0`"
2655.br
2656> set frsl="`echotc fs`"
2657.br
2658> echo \-n "$tosl";date; echo \-n "$frsl"
2659.PP
2660With \fB\-s\fR, nonexistent capabilities return the empty string rather
2661than causing an error.
2662With \fB\-v\fR, messages are verbose.
2663.RE
2664.PP
2665.B else
2666.br
2667.B end
2668.br
2669.B endif
2670.PD 0
2671.TP 8
2672.B endsw
2673See the description of the \fIforeach\fR, \fIif\fR, \fIswitch\fR, and
2674\fIwhile\fR statements below.
2675.PD
2676.TP 8
2677.B eval \fIarg\fR ...
2678Treats the arguments as input to the
2679shell and executes the resulting command(s) in the context
2680of the current shell. This is usually used to execute commands
2681generated as the result of command or variable substitution,
2682because parsing occurs before these substitutions.
2683See \fItset\fR(1) for a sample use of \fIeval\fR.
2684.TP 8
2685.B exec \fIcommand\fR
2686Executes the specified command in place of the current shell.
2687.TP 8
2688.B exit \fR[\fIexpr\fR]
2689The shell exits either with the value of the specified \fIexpr\fR
2690(an expression, as described under \fBExpressions\fR)
2691or, without \fIexpr\fR, with the value of the \fBstatus\fR variable.
2692.TP 8
2693.B fg \fR[\fB%\fIjob\fR ...]
2694Brings the specified jobs (or, without arguments, the current job)
2695into the foreground, continuing each if it is stopped.
2696\fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
2697under \fBJobs\fR.
2698See also the \fIrun-fg-editor\fR editor command.
2699.TP 8
2700.B filetest \-\fIop file\fR ... (+)
2701Applies \fIop\fR (which is a file inquiry operator as described under
2702\fBFile inquiry operators\fR) to each \fIfile\fR and returns the results as a
2703space-separated list.
2704.PP
2705.B foreach \fIname \fB(\fIwordlist\fB)
2706.br
2707\&...
2708.PD 0
2709.TP 8
2710.B end
2711Successively sets the variable \fIname\fR to each member of
2712\fIwordlist\fR and executes the sequence of commands between this command
2713and the matching \fIend\fR. (Both \fIforeach\fR and \fIend\fR
2714must appear alone on separate lines.) The builtin command
2715\fIcontinue\fR may be used to continue the loop prematurely and
2716the builtin command \fIbreak\fR to terminate it prematurely.
2717When this command is read from the terminal, the loop is read once
2718prompting with `foreach? ' (or \fBprompt2\fR) before any statements in
2719the loop are executed. If you make a mistake typing in a
2720loop at the terminal you can rub it out.
2721.PD
2722.TP 8
2723.B getspath \fR(+)
2724Prints the system execution path. (TCF only)
2725.TP 8
2726.B getxvers \fR(+)
2727Prints the experimental version prefix. (TCF only)
2728.TP 8
2729.B glob \fIwordlist
2730Like \fIecho\fR, but no `\\' escapes are recognized and words are
2731delimited by null characters in the output. Useful for
2732programs which wish to use the shell to filename expand a list of words.
2733.TP 8
2734.B goto \fIword
2735\fIword\fR is filename and command-substituted to
2736yield a string of the form `label'. The shell rewinds its
2737input as much as possible, searches for a line of the
2738form `label:', possibly preceded by blanks or tabs, and
2739continues execution after that line.
2740.TP 8
2741.B hashstat
2742Prints a statistics line indicating how effective the
2743internal hash table has been at locating commands (and avoiding
2744\fIexec\fR's). An \fIexec\fR is attempted for each component of the
2745\fBpath\fR where the hash function indicates a possible hit, and
2746in each component which does not begin with a `/'.
2747.IP
2748On machines without \fIvfork\fR(2), prints only the number and size of
2749hash buckets.
2750.PP
2751.B history \fR[\fB\-hTr\fR] [\fIn\fR]
2752.br
2753.B history \-S\fR|\fB\-L|\fB\-M \fR[\fIfilename\fR] (+)
2754.PD 0
2755.TP 8
2756.B history \-c \fR(+)
2757The first form prints the history event list.
2758If \fIn\fR is given only the \fIn\fR most recent events are printed or saved.
2759With \fB\-h\fR, the history list is printed without leading numbers. If
2760\fB-T\fR is specified, timestamps are printed also in comment form.
2761(This can be used to
2762produce files suitable for loading with 'history \-L' or 'source \-h'.)
2763With \fB\-r\fR, the order of printing is most recent
2764first rather than oldest first.
2765.PD
2766.RS +8
2767.PP
2768With \fB\-S\fR, the second form saves the history list to \fIfilename\fR.
2769If the first word of the \fBsavehist\fR shell variable is set to a
2770number, at most that many lines are saved. If the second word of
2771\fBsavehist\fR is set to `merge', the history list is merged with the
2772existing history file instead of replacing it (if there is one) and
2773sorted by time stamp. (+) Merging is intended for an environment like
2774the X Window System
2775with several shells in simultaneous use. Currently it succeeds
2776only when the shells quit nicely one after another.
2777.PP
2778With \fB\-L\fR, the shell appends \fIfilename\fR, which is presumably a
2779history list saved by the \fB\-S\fR option or the \fBsavehist\fR mechanism,
2780to the history list.
2781\fB\-M\fR is like \fB\-L\fR, but the contents of \fIfilename\fR are merged
2782into the history list and sorted by timestamp.
2783In either case, \fBhistfile\fR is used if \fIfilename\fR is not given and
2784\fI~/.history\fR is used if \fBhistfile\fR is unset.
2785`history \-L' is exactly like 'source \-h' except that it does not require a
2786filename.
2787.PP
2788Note that login shells do the equivalent of `history \-L' on startup
2789and, if \fBsavehist\fR is set, `history \-S' before exiting.
2790Because only \fI~/.tcshrc\fR is normally sourced before \fI~/.history\fR,
2791\fBhistfile\fR should be set in \fI~/.tcshrc\fR rather than \fI~/.login\fR.
2792.PP
2793If \fBhistlit\fR is set, the first and second forms print and save the literal
2794(unexpanded) form of the history list.
2795.PP
2796The last form clears the history list.
2797.RE
2798.TP 8
2799.B hup \fR[\fIcommand\fR] \fR(+)
2800With \fIcommand\fR, runs \fIcommand\fR such that it will exit on a hangup
2801signal and arranges for the shell to send it a hangup signal when the shell
2802exits.
2803Note that commands may set their own response to hangups, overriding \fIhup\fR.
2804Without an argument (allowed in only a shell script), causes the shell to
2805exit on a hangup for the remainder of the script.
2806See also \fBSignal handling\fR and the \fInohup\fR builtin command.
2807.TP 8
2808.B if (\fIexpr\fB) \fIcommand
2809If \fIexpr\fR (an expression, as described under \fBExpressions\fR)
2810evaluates true, then \fIcommand\fR is executed.
2811Variable substitution on \fIcommand\fR happens early, at the same time it
2812does for the rest of the \fIif\fR command.
2813\fIcommand\fR must be a simple command, not an alias, a pipeline, a command list
2814or a parenthesized command list, but it may have arguments.
2815Input/output redirection occurs even if \fIexpr\fR is
2816false and \fIcommand\fR is thus \fInot\fR executed; this is a bug.
2817.PP
2818.B if (\fIexpr\fB) then
2819.br
2820\&...
2821.br
2822.B else if (\fIexpr2\fB) then
2823.br
2824\&...
2825.br
2826.B else
2827.br
2828\&...
2829.PD 0
2830.TP 8
2831.B endif
2832If the specified \fIexpr\fR is true then the commands to the
2833first \fIelse\fR are executed; otherwise if \fIexpr2\fR is true then
2834the commands to the second \fIelse\fR are executed, etc. Any
2835number of \fIelse-if\fR pairs are possible; only one \fIendif\fR is
2836needed. The \fIelse\fR part is likewise optional. (The words
2837\fIelse\fR and \fIendif\fR must appear at the beginning of input lines;
2838the \fIif\fR must appear alone on its input line or after an
2839\fIelse\fR.)
2840.PD
2841.TP 8
2842.B inlib \fIshared-library\fR ... (+)
2843Adds each \fIshared-library\fR to the current environment. There is no way
2844to remove a shared library. (Domain/OS only)
2845.TP 8
2846.B jobs \fR[\fB\-l\fR]
2847Lists the active jobs. With \fB\-l\fR, lists process
2848IDs in addition to the normal information. On TCF systems, prints
2849the site on which each job is executing.
2850.PP
| 1895.PP
1896The \fBautologout\fR shell variable can be set to log out or lock the shell
1897after a given number of minutes of inactivity.
1898.PP
1899The \fBmail\fR shell variable can be set to check for new mail periodically.
1900.PP
1901The \fBprintexitvalue\fR shell variable can be set to print the exit status
1902of commands which exit with a status other than zero.
1903.PP
1904The \fBrmstar\fR shell variable can be set to ask the user, when `rm *' is
1905typed, if that is really what was meant.
1906.PP
1907The \fBtime\fR shell variable can be set to execute the \fItime\fR builtin
1908command after the completion of any process that takes more than a given
1909number of CPU seconds.
1910.PP
1911The \fBwatch\fR and \fBwho\fR shell variables can be set to report when
1912selected users log in or out, and the \fIlog\fR builtin command reports
1913on those users at any time.
1914.SS "Native Language System support (+)"
1915The shell is eight bit clean
1916(if so compiled; see the \fBversion\fR shell variable)
1917and thus supports character sets needing this capability.
1918NLS support differs depending on whether or not
1919the shell was compiled to use the system's NLS (again, see \fBversion\fR).
1920In either case, 7-bit ASCII is the default for character classification
1921(e.g., which characters are printable) and sorting,
1922and changing the \fBLANG\fR or \fBLC_CTYPE\fR environment variables
1923causes a check for possible changes in these respects.
1924.PP
1925When using the system's NLS, the \fIsetlocale\fR(3) function is called
1926to determine appropriate character classification and sorting.
1927This function typically examines the \fBLANG\fR and \fBLC_CTYPE\fR
1928environment variables; refer to the system documentation for further details.
1929When not using the system's NLS, the shell simulates it by assuming that the
1930ISO 8859-1 character set is used
1931whenever either of the \fBLANG\fR and \fBLC_CTYPE\fR variables are set, regardless of
1932their values. Sorting is not affected for the simulated NLS.
1933.PP
1934In addition, with both real and simulated NLS, all printable
1935characters in the range \e200\-\e377, i.e., those that have
1936M-\fIchar\fR bindings, are automatically rebound to \fIself-insert-command\fR.
1937The corresponding binding for the escape-\fIchar\fR sequence, if any, is
1938left alone.
1939These characters are not rebound if the \fBNOREBIND\fR environment variable
1940is set. This may be useful for the simulated NLS or a primitive real NLS
1941which assumes full ISO 8859-1. Otherwise, all M-\fIchar\fR bindings in the
1942range \e240\-\e377 are effectively undone.
1943Explicitly rebinding the relevant keys with \fIbindkey\fR
1944is of course still possible.
1945.PP
1946Unknown characters (i.e., those that are neither printable nor control
1947characters) are printed in the format \ennn.
1948If the tty is not in 8 bit mode, other 8 bit characters are printed by
1949converting them to ASCII and using standout mode. The shell
1950never changes the 7/8 bit mode of the tty and tracks user-initiated
1951changes of 7/8 bit mode. NLS users (or, for that matter, those who want to
1952use a meta key) may need to explicitly set
1953the tty in 8 bit mode through the appropriate \fIstty\fR(1)
1954command in, e.g., the \fI~/.login\fR file.
1955.SS "OS variant support (+)"
1956A number of new builtin commands are provided to support features in
1957particular operating systems. All are described in detail in the
1958\fBBuiltin commands\fR section.
1959.PP
1960On systems that support TCF (aix-ibm370, aix-ps2),
1961\fIgetspath\fR and \fIsetspath\fR get and set the system execution path,
1962\fIgetxvers\fR and \fIsetxvers\fR get and set the experimental version prefix
1963and \fImigrate\fR migrates processes between sites. The \fIjobs\fR builtin
1964prints the site on which each job is executing.
1965.PP
1966Under Domain/OS, \fIinlib\fR adds shared libraries to the current environment,
1967\fIrootnode\fR changes the rootnode and \fIver\fR changes the systype.
1968.PP
1969Under Mach, \fIsetpath\fR is equivalent to Mach's \fIsetpath\fR(1).
1970.PP
1971Under Masscomp/RTU and Harris CX/UX, \fIuniverse\fR sets the universe.
1972.PP
1973Under Harris CX/UX, \fIucb\fR or \fIatt\fR runs a command under the specified
1974universe.
1975.PP
1976Under Convex/OS, \fIwarp\fR prints or sets the universe.
1977.PP
1978The \fBVENDOR\fR, \fBOSTYPE\fR and \fBMACHTYPE\fR environment variables
1979indicate respectively the vendor, operating system and machine type
1980(microprocessor class or machine model) of the
1981system on which the shell thinks it is running.
1982These are particularly useful when sharing one's home directory between several
1983types of machines; one can, for example,
1984.IP "" 4
1985set path = (~/bin.$MACHTYPE /usr/ucb /bin /usr/bin .)
1986.PP
1987in one's \fI~/.login\fR and put executables compiled for each machine in the
1988appropriate directory.
1989.PP
1990The \fBversion\fR shell
1991variable indicates what options were chosen when the shell was compiled.
1992.PP
1993Note also the \fInewgrp\fR builtin, the \fBafsuser\fR and
1994\fBecho_style\fR shell variables and the system-dependent locations of
1995the shell's input files (see \fBFILES\fR).
1996.SS "Signal handling"
1997Login shells ignore interrupts when reading the file \fI~/.logout\fR.
1998The shell ignores quit signals unless started with \fB\-q\fR.
1999Login shells catch the terminate signal, but non-login shells inherit the
2000terminate behavior from their parents.
2001Other signals have the values which the shell inherited from its parent.
2002.PP
2003In shell scripts, the shell's handling of interrupt and terminate signals
2004can be controlled with \fIonintr\fR, and its handling of hangups can be
2005controlled with \fIhup\fR and \fInohup\fR.
2006.PP
2007The shell exits on a hangup (see also the \fBlogout\fR shell variable). By
2008default, the shell's children do too, but the shell does not send them a
2009hangup when it exits. \fIhup\fR arranges for the shell to send a hangup to
2010a child when it exits, and \fInohup\fR sets a child to ignore hangups.
2011.SS "Terminal management (+)"
2012The shell uses three different sets of terminal (``tty'') modes:
2013`edit', used when editing, `quote', used when quoting literal characters,
2014and `execute', used when executing commands.
2015The shell holds some settings in each mode constant, so commands which leave
2016the tty in a confused state do not interfere with the shell.
2017The shell also matches changes in the speed and padding of the tty.
2018The list of tty modes that are kept constant
2019can be examined and modified with the \fIsetty\fR builtin.
2020Note that although the editor uses CBREAK mode (or its equivalent),
2021it takes typed-ahead characters anyway.
2022.PP
2023The \fIechotc\fR, \fIsettc\fR and \fItelltc\fR commands can be used to
2024manipulate and debug terminal capabilities from the command line.
2025.PP
2026On systems that support SIGWINCH or SIGWINDOW, the shell
2027adapts to window resizing automatically and adjusts the environment
2028variables \fBLINES\fR and \fBCOLUMNS\fR if set. If the environment
2029variable \fBTERMCAP\fR contains li# and co# fields, the shell adjusts
2030them to reflect the new window size.
2031.SH REFERENCE
2032The next sections of this manual describe all of the available
2033\fBBuiltin commands\fR, \fBSpecial aliases\fR and
2034\fBSpecial shell variables\fR.
2035.SS "Builtin commands"
2036.TP 8
2037.B %\fIjob
2038A synonym for the \fIfg\fR builtin command.
2039.TP 8
2040.B %\fIjob \fB&
2041A synonym for the \fIbg\fR builtin command.
2042.TP 8
2043.B :
2044Does nothing, successfully.
2045.PP
2046.B @
2047.br
2048.B @ \fIname\fB = \fIexpr
2049.br
2050.B @ \fIname\fR[\fIindex\fR]\fB = \fIexpr
2051.br
2052.B @ \fIname\fB++\fR|\fB--
2053.PD 0
2054.TP 8
2055.B @ \fIname\fR[\fIindex\fR]\fB++\fR|\fB--
2056The first form prints the values of all shell variables.
2057.PD
2058.RS +8
2059.PP
2060The second form assigns the value of \fIexpr\fR to \fIname\fR.
2061The third form assigns the value of \fIexpr\fR to the \fIindex\fR'th
2062component of \fIname\fR; both \fIname\fR and its \fIindex\fR'th component
2063must already exist.
2064.PP
2065\fIexpr\fR may contain the operators `*', `+', etc., as in C.
2066If \fIexpr\fR contains `<', `>', `&' or `' then at least that part of
2067\fIexpr\fR must be placed within `()'.
2068Note that the syntax of \fIexpr\fR has nothing to do with that described
2069under \fBExpressions\fR.
2070.PP
2071The fourth and fifth forms increment (`++') or decrement (`\-\-') \fIname\fR
2072or its \fIindex\fR'th component.
2073.PP
2074The space between `@' and \fIname\fR is required. The spaces between
2075\fIname\fR and `=' and between `=' and \fIexpr\fR are optional. Components of
2076\fIexpr\fR must be separated by spaces.
2077.RE
2078.PD
2079.TP 8
2080.B alias \fR[\fIname \fR[\fIwordlist\fR]]
2081Without arguments, prints all aliases.
2082With \fIname\fR, prints the alias for name.
2083With \fIname\fR and \fIwordlist\fR, assigns
2084\fIwordlist\fR as the alias of \fIname\fR.
2085\fIwordlist\fR is command and filename substituted.
2086\fIname\fR may not be `alias' or `unalias'.
2087See also the \fIunalias\fR builtin command.
2088.ig \" Obsolete tcsh command
2089.TP 8
2090.B aliases \fR[\fIfile\fR] (+)
2091Without arguments, prints all aliases.
2092With \fIfile\fR, loads a list of aliases from \fIfile\fR, one per line.
2093Retained for only downward compatibility.
2094..
2095.TP 8
2096.B alloc
2097Shows the amount of dynamic memory acquired, broken down into used and free
2098memory. With an argument shows the number of free and used blocks in each size
2099category. The categories start at size 8 and double at each step. This
2100command's output may vary across system types, because systems other than the VAX
2101may use a different memory allocator.
2102.TP 8
2103.B bg \fR[\fB%\fIjob\fR ...]
2104Puts the specified jobs (or, without arguments, the current job)
2105into the background, continuing each if it is stopped.
2106\fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
2107under \fBJobs\fR.
2108.ig \" Obsolete tcsh command
2109.TP 8
2110.B bind \fR[\fBdefaults\fR|\fBemacs\fR|\fBvi\fR|\fIkey\fR|\fIkey command\fR] (+)
2111An older version of \fIbindkey\fR, retained for only downward compatibility.
2112Without arguments, lists all bound keys and the editor command to which each is bound.
2113`bind defaults', `bind emacs' and `bind vi' are equivalent to
2114`bindkey \-d', `bindkey \-e' and `bindkey \-v'.
2115With \fIkey\fR, lists the editor command to which \fIkey\fR is bound.
2116With \fIkey\fR and \fIcommand\fR, binds the editor command \fIcommand\fR to \fIkey\fR.
2117.IP "" 8
2118\fIkey\fR may be a literal character,
2119a control character written ^\fIcharacter\fR (e.g., `^A'),
2120a meta character written M-\fIcharacter\fR (e.g., `M-A')
2121or a function key written F-\fIstring\fR (e.g., `F-foo').
2122For the function key form to work, the function key prefix must be
2123bound to \fIsequence-lead-in\fR and \fIstring\fR must not contain that prefix.
2124..
2125.PP
2126.B bindkey \fR[\fB\-l\fR|\fB\-d\fR|\fB\-e\fR|\fB\-v\fR|\fB\-u\fR] (+)
2127.br
2128\fBbindkey \fR[\fB\-a\fR] [\fB\-b\fR] [\fB\-k\fR] [\fB\-r\fR] [\fB\-\-\fR] \fIkey \fR(+)
2129.PD 0
2130.TP 8
2131\fBbindkey \fR[\fB\-a\fR] [\fB\-b\fR] [\fB\-k\fR] [\fB\-c\fR|\fB\-s\fR] [\fB\-\-\fR] \fIkey command \fR(+)
2132.\" .B macro can't take too many words, so I used \fB in the previous tags
2133Without options, the first form lists all bound keys and the editor command to which each is bound,
2134the second form lists the editor command to which \fIkey\fR is bound and
2135the third form binds the editor command \fIcommand\fR to \fIkey\fR.
2136Options include:
2137.PD
2138.PP
2139.PD 0
2140.RS +8
2141.TP 4
2142.B \-l
2143Lists all editor commands and a short description of each.
2144.TP 4
2145.B \-d
2146Binds all keys to the standard bindings for the default editor.
2147.TP 4
2148.B \-e
2149Binds all keys to the standard GNU Emacs-like bindings.
2150.TP 4
2151.B \-v
2152Binds all keys to the standard \fIvi\fR(1)-like bindings.
2153.TP 4
2154.B \-a
2155Lists or changes key-bindings in the alternative key map.
2156This is the key map used in \fIvi\fR command mode.
2157.TP 4
2158.B \-b
2159\fIkey\fR is interpreted as
2160a control character written ^\fIcharacter\fR (e.g., `^A') or
2161C-\fIcharacter\fR (e.g., `C-A'),
2162a meta character written M-\fIcharacter\fR (e.g., `M-A'),
2163a function key written F-\fIstring\fR (e.g., `F-string'),
2164or an extended prefix key written X-\fIcharacter\fR (e.g., `X-A').
2165.TP 4
2166.B \-k
2167\fIkey\fR is interpreted as a symbolic arrow key name, which may be one of
2168`down', `up', `left' or `right'.
2169.TP 4
2170.B \-r
2171Removes \fIkey\fR's binding.
2172Be careful: `bindkey \-r' does \fInot\fR bind \fIkey\fR to
2173\fIself-insert-command\fR (q.v.), it unbinds \fIkey\fR completely.
2174.TP 4
2175.B \-c
2176\fIcommand\fR is interpreted as a builtin or external command instead of an
2177editor command.
2178.TP 4
2179.B \-s
2180\fIcommand\fR is taken as a literal string and treated as terminal input
2181when \fIkey\fR is typed. Bound keys in \fIcommand\fR are themselves
2182reinterpreted, and this continues for ten levels of interpretation.
2183.TP 4
2184.B \-\-
2185Forces a break from option processing, so the next word is taken as \fIkey\fR
2186even if it begins with '\-'.
2187.TP 4
2188.B \-u \fR(or any invalid option)
2189Prints a usage message.
2190.PD
2191.PP
2192\fIkey\fR may be a single character or a string.
2193If a command is bound to a string, the first character of the string is bound to
2194\fIsequence-lead-in\fR and the entire string is bound to the command.
2195.PP
2196Control characters in \fIkey\fR can be literal (they can be typed by preceding
2197them with the editor command \fIquoted-insert\fR, normally bound to `^V') or
2198written caret-character style, e.g., `^A'. Delete is written `^?'
2199(caret-question mark). \fIkey\fR and \fIcommand\fR can contain backslashed
2200escape sequences (in the style of System V \fIecho\fR(1)) as follows:
2201.RS +4
2202.TP 8
2203.PD 0
2204.B \ea
2205Bell
2206.TP 8
2207.B \eb
2208Backspace
2209.TP 8
2210.B \ee
2211Escape
2212.TP 8
2213.B \ef
2214Form feed
2215.TP 8
2216.B \en
2217Newline
2218.TP 8
2219.B \er
2220Carriage return
2221.TP 8
2222.B \et
2223Horizontal tab
2224.TP 8
2225.B \ev
2226Vertical tab
2227.TP 8
2228.B \e\fInnn
2229The ASCII character corresponding to the octal number \fInnn\fR
2230.PD
2231.RE
2232.PP
2233`\e' nullifies the special meaning of the following character, if it has
2234any, notably `\\' and `^'.
2235.RE
2236.TP 8
2237.B break
2238Causes execution to resume after the \fIend\fR of the nearest
2239enclosing \fIforeach\fR or \fIwhile\fR. The remaining commands on the
2240current line are executed. Multi-level breaks are thus
2241possible by writing them all on one line.
2242.TP 8
2243.B breaksw
2244Causes a break from a \fIswitch\fR, resuming after the \fIendsw\fR.
2245.TP 8
2246.B builtins \fR(+)
2247Prints the names of all builtin commands.
2248.TP 8
2249.B bye \fR(+)
2250A synonym for the \fIlogout\fR builtin command.
2251Available only if the shell was so compiled;
2252see the \fBversion\fR shell variable.
2253.TP 8
2254.B case \fIlabel\fB:
2255A label in a \fIswitch\fR statement as discussed below.
2256.TP 8
2257.B cd \fR[\fB\-p\fR] [\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR] [\fIname\fR]
2258If a directory \fIname\fR is given, changes the shell's working directory
2259to \fIname\fR. If not, changes to \fBhome\fR.
2260If \fIname\fR is `\-' it is interpreted as the previous working directory
2261(see \fBOther substitutions\fR). (+)
2262If \fIname\fR is not a subdirectory of the current directory
2263(and does not begin with `/', `./' or `../'), each component of the variable
2264\fBcdpath\fR is checked to see if it has a subdirectory \fIname\fR. Finally, if
2265all else fails but \fIname\fR is a shell variable whose value
2266begins with `/', then this is tried to see if it is a directory.
2267.RS +8
2268.PP
2269With \fB\-p\fR, prints the final directory stack, just like \fIdirs\fR.
2270The \fB\-l\fR, \fB\-n\fR and \fB\-v\fR flags have the same effect on \fIcd\fR
2271as on \fIdirs\fR, and they imply \fB\-p\fR. (+)
2272.PP
2273See also the \fBimplicitcd\fR shell variable.
2274.RE
2275.TP 8
2276.B chdir
2277A synonym for the \fIcd\fR builtin command.
2278.TP 8
2279.B complete \fR[\fIcommand\fR [\fIword\fB/\fIpattern\fB/\fIlist\fR[\fB:\fIselect\fR]\fB/\fR[[\fIsuffix\fR]\fB/\fR] ...]] (+)
2280Without arguments, lists all completions.
2281With \fIcommand\fR, lists completions for \fIcommand\fR.
2282With \fIcommand\fR and \fIword\fR etc., defines completions.
2283.RS +8
2284.PP
2285\fIcommand\fR may be a full command name or a glob-pattern
2286(see \fBFilename substitution\fR). It can begin with `\-' to indicate that
2287completion should be used only when \fIcommand\fR is ambiguous.
2288.PP
2289\fIword\fR specifies which word relative to the current word
2290is to be completed, and may be one of the following:
2291.PP
2292.PD 0
2293.RS +4
2294.TP 4
2295.B c
2296Current-word completion.
2297\fIpattern\fR is a glob-pattern which must match the beginning of the current word on
2298the command line. \fIpattern\fR is ignored when completing the current word.
2299.TP 4
2300.B C
2301Like \fBc\fR, but includes \fIpattern\fR when completing the current word.
2302.TP 4
2303.B n
2304Next-word completion.
2305\fIpattern\fR is a glob-pattern which must match the beginning of the previous word on
2306the command line.
2307.TP 4
2308.B N
2309Like \fBn\fR, but must match the beginning of the word two before the current word.
2310.TP 4
2311.B p
2312Position-dependent completion.
2313\fIpattern\fR is a numeric range, with the same syntax used to index shell
2314variables, which must include the current word.
2315.PD
2316.RE
2317.ig \" No longer true in 6.05.04
2318.PP
2319When \fIpattern\fR is a glob-pattern (for \fBc\fR, \fBC\fR, \fBn\fR and
2320\fBN\fR-type completion), a \fIpattern\fR of `*' does not match an empty
2321word.
2322..
2323.PP
2324\fIlist\fR, the list of possible completions, may be one of the following:
2325.PP
2326.PD 0
2327.RS +4
2328.TP 8
2329.B a
2330Aliases
2331.TP 8
2332.B b
2333Bindings (editor commands)
2334.TP 8
2335.B c
2336Commands (builtin or external commands)
2337.TP 8
2338.B C
2339External commands which begin with the supplied path prefix
2340.TP 8
2341.B d
2342Directories
2343.TP 8
2344.B D
2345Directories which begin with the supplied path prefix
2346.TP 8
2347.B e
2348Environment variables
2349.TP 8
2350.B f
2351Filenames
2352.TP 8
2353.B F
2354Filenames which begin with the supplied path prefix
2355.TP 8
2356.B g
2357Groupnames
2358.TP 8
2359.B j
2360Jobs
2361.TP 8
2362.B l
2363Limits
2364.TP 8
2365.B n
2366Nothing
2367.TP 8
2368.B s
2369Shell variables
2370.TP 8
2371.B S
2372Signals
2373.TP 8
2374.B t
2375Plain (``text'') files
2376.TP 8
2377.B T
2378Plain (``text'') files which begin with the supplied path prefix
2379.TP 8
2380.B v
2381Any variables
2382.TP 8
2383.B u
2384Usernames
2385.TP 8
2386.B x
2387Like \fBn\fR, but prints \fIselect\fR when \fIlist-choices\fR is used.
2388.TP 8
2389.B X
2390Completions
2391.TP 8
2392$\fIvar\fR
2393Words from the variable \fIvar\fR
2394.TP 8
2395(...)
2396Words from the given list
2397.TP 8
2398`...`
2399Words from the output of command
2400.PD
2401.RE
2402.PP
2403\fIselect\fR is an optional glob-pattern.
2404If given, words from only \fIlist\fR that match \fIselect\fR are considered
2405and the \fBfignore\fR shell variable is ignored.
2406The last three types of completion may not have a \fIselect\fR
2407pattern, and \fBx\fR uses \fIselect\fR as an explanatory message when
2408the \fIlist-choices\fR editor command is used.
2409.PP
2410\fIsuffix\fR is a single character to be appended to a successful
2411completion. If null, no character is appended. If omitted (in which
2412case the fourth delimiter can also be omitted), a slash is appended to
2413directories and a space to other words.
2414.PP
2415Now for some examples. Some commands take only directories as arguments,
2416so there's no point completing plain files.
2417.IP "" 4
2418> complete cd 'p/1/d/'
2419.PP
2420completes only the first word following `cd' (`p/1') with a directory.
2421\fBp\fR-type completion can also be used to narrow down command completion:
2422.IP "" 4
2423> co[^D]
2424.br
2425complete compress
2426.br
2427> complete \-co* 'p/0/(compress)/'
2428.br
2429> co[^D]
2430.br
2431> compress
2432.PP
2433This completion completes commands (words in position 0, `p/0')
2434which begin with `co' (thus matching `co*') to `compress' (the only
2435word in the list).
2436The leading `\-' indicates that this completion is to be used with only
2437ambiguous commands.
2438.IP "" 4
2439> complete find 'n/\-user/u/'
2440.PP
2441is an example of \fBn\fR-type completion. Any word following `find' and
2442immediately following `\-user' is completed from the list of users.
2443.IP "" 4
2444> complete cc 'c/\-I/d/'
2445.PP
2446demonstrates \fBc\fR-type completion. Any word following `cc' and beginning
2447with `\-I' is completed as a directory. `\-I' is not taken as part of the
2448directory because we used lowercase \fBc\fR.
2449.PP
2450Different \fIlist\fRs are useful with different commands.
2451.IP "" 4
2452> complete alias 'p/1/a/'
2453.br
2454> complete man 'p/*/c/'
2455.br
2456> complete set 'p/1/s/'
2457.br
2458> complete true 'p/1/x:Truth has no options./'
2459.PP
2460These complete words following `alias' with aliases, `man' with commands,
2461and `set' with shell variables.
2462`true' doesn't have any options, so \fBx\fR does nothing when completion
2463is attempted and prints `Truth has no options.' when completion choices are listed.
2464.PP
2465.ig \" Changed in 6.05.04
2466The \fIman\fR example, and several other examples below, use
2467\fBp\fR-type completion, rather than \fBC\fR- or \fBn\fR-type, so that
2468`*' will match an empty word.
2469..
2470Note that the \fIman\fR example, and several other examples below, could
2471just as well have used 'c/*' or 'n/*' as 'p/*'.
2472.PP
2473Words can be completed from a variable evaluated at completion time,
2474.IP "" 4
2475> complete ftp 'p/1/$hostnames/'
2476.br
2477> set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu)
2478.br
2479> ftp [^D]
2480.br
2481rtfm.mit.edu tesla.ee.cornell.edu
2482.br
2483> ftp [^C]
2484.br
2485> set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net)
2486.br
2487> ftp [^D]
2488.br
2489rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net
2490.PP
2491or from a command run at completion time:
2492.IP "" 4
2493> complete kill 'p/*/`ps | awk \\{print\\ \\$1\\}`/'
2494.br
2495> kill \-9 [^D]
2496.br
249723113 23377 23380 23406 23429 23529 23530 PID
2498.PP
2499Note that the \fIcomplete\fR command does not itself quote its arguments,
2500so the braces, space and `$' in `{print $1}' must be quoted explicitly.
2501.PP
2502One command can have multiple completions:
2503.IP "" 4
2504> complete dbx 'p/2/(core)/' 'p/*/c/'
2505.PP
2506completes the second argument to `dbx' with the word `core' and all other
2507arguments with commands. Note that the positional completion is specified
2508before the next-word completion.
2509Because completions are evaluated from left to right, if
2510the next-word completion were specified first it would always match
2511and the positional completion would never be executed. This is a
2512common mistake when defining a completion.
2513.PP
2514The \fIselect\fR pattern is useful when a command takes files with only
2515particular forms as arguments. For example,
2516.IP "" 4
2517> complete cc 'p/*/f:*.[cao]/'
2518.PP
2519completes `cc' arguments to files ending in only `.c', `.a', or `.o'.
2520\fIselect\fR can also exclude files, using negation of a glob-pattern as
2521described under \fBFilename substitution\fR. One might use
2522.IP "" 4
2523> complete rm 'p/*/f:^*.{c,h,cc,C,tex,1,man,l,y}/'
2524.PP
2525to exclude precious source code from `rm' completion. Of course, one
2526could still type excluded names manually or override the completion
2527mechanism using the \fIcomplete-word-raw\fR or \fIlist-choices-raw\fR
2528editor commands (q.v.).
2529.PP
2530The `C', `D', `F' and `T' \fIlist\fRs are like `c', `d', `f' and `t'
2531respectively, but they use the \fIselect\fR argument in a different way: to
2532restrict completion to files beginning with a particular path prefix. For
2533example, the Elm mail program uses `=' as an abbreviation for one's mail
2534directory. One might use
2535.IP "" 4
2536> complete elm c@=@F:$HOME/Mail/@
2537.PP
2538to complete `elm \-f =' as if it were `elm \-f ~/Mail/'. Note that we used `@'
2539instead of `/' to avoid confusion with the \fIselect\fR argument, and we used
2540`$HOME' instead of `~' because home directory substitution works at only the
2541beginning of a word.
2542.PP
2543\fIsuffix\fR is used to add a nonstandard suffix
2544(not space or `/' for directories) to completed words.
2545.IP "" 4
2546> complete finger 'c/*@/$hostnames/' 'p/1/u/@'
2547.PP
2548completes arguments to `finger' from the list of users, appends an `@',
2549and then completes after the `@' from the `hostnames' variable. Note
2550again the order in which the completions are specified.
2551.PP
2552Finally, here's a complex example for inspiration:
2553.IP "" 4
2554> complete find \\
2555.br
2556\'n/\-name/f/' 'n/\-newer/f/' 'n/\-{,n}cpio/f/' \e
2557.br
2558\'n/\-exec/c/' 'n/\-ok/c/' 'n/\-user/u/' \e
2559.br
2560\'n/\-group/g/' 'n/\-fstype/(nfs 4.2)/' \e
2561.br
2562\'n/\-type/(b c d f l p s)/' \e
2563.br
2564\'c/\-/(name newer cpio ncpio exec ok user \e
2565.br
2566group fstype type atime ctime depth inum \e
2567.br
2568ls mtime nogroup nouser perm print prune \e
2569.br
2570size xdev)/' \e
2571.br
2572\'p/*/d/'
2573.PP
2574This completes words following `\-name', `\-newer', `\-cpio' or `ncpio'
2575(note the pattern which matches both) to files,
2576words following `\-exec' or `\-ok' to commands, words following `user'
2577and `group' to users and groups respectively
2578and words following `\-fstype' or `\-type' to members of the
2579given lists. It also completes the switches themselves from the given list
2580(note the use of \fBc\fR-type completion)
2581and completes anything not otherwise completed to a directory. Whew.
2582.PP
2583Remember that programmed completions are ignored if the word being completed
2584is a tilde substitution (beginning with `~') or a variable (beginning with `$').
2585\fIcomplete\fR is an experimental feature, and the syntax may change
2586in future versions of the shell.
2587See also the \fIuncomplete\fR builtin command.
2588.RE
2589.TP 8
2590.B continue
2591Continues execution of the nearest enclosing \fIwhile\fR or \fIforeach\fR.
2592The rest of the commands on the current line are executed.
2593.TP 8
2594.B default:
2595Labels the default case in a \fIswitch\fR statement.
2596It should come after all \fIcase\fR labels.
2597.PP
2598.B dirs \fR[\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR]
2599.br
2600.B dirs \-S\fR|\fB\-L \fR[\fIfilename\fR] (+)
2601.PD 0
2602.TP 8
2603.B dirs \-c \fR(+)
2604The first form prints the directory stack. The top of the stack is at the
2605left and the first directory in the stack is the current directory.
2606With \fB\-l\fR, `~' or `~\fIname\fP' in the output is expanded explicitly
2607to \fBhome\fR or the pathname of the home directory for user \fIname\fP. (+)
2608With \fB\-n\fR, entries are wrapped before they reach the edge of the screen. (+)
2609With \fB\-v\fR, entries are printed one per line, preceded by their stack positions. (+)
2610If more than one of \fB\-n\fR or \fB\-v\fR is given, \fB\-v\fR takes precedence.
2611\fB\-p\fR is accepted but does nothing.
2612.PD
2613.RS +8
2614.PP
2615With \fB\-S\fR, the second form saves the directory stack to \fIfilename\fR
2616as a series of \fIcd\fR and \fIpushd\fR commands.
2617With \fB\-L\fR, the shell sources \fIfilename\fR, which is presumably
2618a directory stack file saved by the \fB\-S\fR option or the \fBsavedirs\fR
2619mechanism.
2620In either case, \fBdirsfile\fR is used if \fIfilename\fR is not given and
2621\fI~/.cshdirs\fR is used if \fBdirsfile\fR is unset.
2622.PP
2623Note that login shells do the equivalent of `dirs \-L' on startup
2624and, if \fBsavedirs\fR is set, `dirs \-S' before exiting.
2625Because only \fI~/.tcshrc\fR is normally sourced before \fI~/.cshdirs\fR,
2626\fBdirsfile\fR should be set in \fI~/.tcshrc\fR rather than \fI~/.login\fR.
2627.PP
2628The last form clears the directory stack.
2629.RE
2630.TP 8
2631.B echo \fR[\fB\-n\fR] \fIword\fR ...
2632Writes each \fIword\fR to the shell's standard
2633output, separated by spaces and terminated with a newline.
2634The \fBecho_style\fR shell variable may be set to emulate (or not) the flags and escape
2635sequences of the BSD and/or System V versions of \fIecho\fR; see \fIecho\fR(1).
2636.TP 8
2637.B echotc \fR[\fB\-sv\fR] \fIarg\fR ... (+)
2638Exercises the terminal capabilities (see \fItermcap\fR(5)) in \fIargs\fR.
2639For example, 'echotc home' sends the cursor to the home position,
2640\&'echotc cm 3 10' sends it to column 3 and row 10, and
2641\&'echotc ts 0; echo "This is a test."; echotc fs' prints "This is a test."
2642in the status line.
2643.RS +8
2644.PP
2645If \fIarg\fR is 'baud', 'cols', 'lines', 'meta' or 'tabs', prints the
2646value of that capability ("yes" or "no" indicating that the terminal does
2647or does not have that capability). One might use this to make the output
2648from a shell script less verbose on slow terminals, or limit command
2649output to the number of lines on the screen:
2650.IP "" 4
2651> set history=`echotc lines`
2652.br
2653> @ history\-\-
2654.PP
2655Termcap strings may contain wildcards which will not echo correctly.
2656One should use double quotes when setting a shell variable to a terminal
2657capability string, as in the following example that places the date in
2658the status line:
2659.IP "" 4
2660> set tosl="`echotc ts 0`"
2661.br
2662> set frsl="`echotc fs`"
2663.br
2664> echo \-n "$tosl";date; echo \-n "$frsl"
2665.PP
2666With \fB\-s\fR, nonexistent capabilities return the empty string rather
2667than causing an error.
2668With \fB\-v\fR, messages are verbose.
2669.RE
2670.PP
2671.B else
2672.br
2673.B end
2674.br
2675.B endif
2676.PD 0
2677.TP 8
2678.B endsw
2679See the description of the \fIforeach\fR, \fIif\fR, \fIswitch\fR, and
2680\fIwhile\fR statements below.
2681.PD
2682.TP 8
2683.B eval \fIarg\fR ...
2684Treats the arguments as input to the
2685shell and executes the resulting command(s) in the context
2686of the current shell. This is usually used to execute commands
2687generated as the result of command or variable substitution,
2688because parsing occurs before these substitutions.
2689See \fItset\fR(1) for a sample use of \fIeval\fR.
2690.TP 8
2691.B exec \fIcommand\fR
2692Executes the specified command in place of the current shell.
2693.TP 8
2694.B exit \fR[\fIexpr\fR]
2695The shell exits either with the value of the specified \fIexpr\fR
2696(an expression, as described under \fBExpressions\fR)
2697or, without \fIexpr\fR, with the value of the \fBstatus\fR variable.
2698.TP 8
2699.B fg \fR[\fB%\fIjob\fR ...]
2700Brings the specified jobs (or, without arguments, the current job)
2701into the foreground, continuing each if it is stopped.
2702\fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
2703under \fBJobs\fR.
2704See also the \fIrun-fg-editor\fR editor command.
2705.TP 8
2706.B filetest \-\fIop file\fR ... (+)
2707Applies \fIop\fR (which is a file inquiry operator as described under
2708\fBFile inquiry operators\fR) to each \fIfile\fR and returns the results as a
2709space-separated list.
2710.PP
2711.B foreach \fIname \fB(\fIwordlist\fB)
2712.br
2713\&...
2714.PD 0
2715.TP 8
2716.B end
2717Successively sets the variable \fIname\fR to each member of
2718\fIwordlist\fR and executes the sequence of commands between this command
2719and the matching \fIend\fR. (Both \fIforeach\fR and \fIend\fR
2720must appear alone on separate lines.) The builtin command
2721\fIcontinue\fR may be used to continue the loop prematurely and
2722the builtin command \fIbreak\fR to terminate it prematurely.
2723When this command is read from the terminal, the loop is read once
2724prompting with `foreach? ' (or \fBprompt2\fR) before any statements in
2725the loop are executed. If you make a mistake typing in a
2726loop at the terminal you can rub it out.
2727.PD
2728.TP 8
2729.B getspath \fR(+)
2730Prints the system execution path. (TCF only)
2731.TP 8
2732.B getxvers \fR(+)
2733Prints the experimental version prefix. (TCF only)
2734.TP 8
2735.B glob \fIwordlist
2736Like \fIecho\fR, but no `\\' escapes are recognized and words are
2737delimited by null characters in the output. Useful for
2738programs which wish to use the shell to filename expand a list of words.
2739.TP 8
2740.B goto \fIword
2741\fIword\fR is filename and command-substituted to
2742yield a string of the form `label'. The shell rewinds its
2743input as much as possible, searches for a line of the
2744form `label:', possibly preceded by blanks or tabs, and
2745continues execution after that line.
2746.TP 8
2747.B hashstat
2748Prints a statistics line indicating how effective the
2749internal hash table has been at locating commands (and avoiding
2750\fIexec\fR's). An \fIexec\fR is attempted for each component of the
2751\fBpath\fR where the hash function indicates a possible hit, and
2752in each component which does not begin with a `/'.
2753.IP
2754On machines without \fIvfork\fR(2), prints only the number and size of
2755hash buckets.
2756.PP
2757.B history \fR[\fB\-hTr\fR] [\fIn\fR]
2758.br
2759.B history \-S\fR|\fB\-L|\fB\-M \fR[\fIfilename\fR] (+)
2760.PD 0
2761.TP 8
2762.B history \-c \fR(+)
2763The first form prints the history event list.
2764If \fIn\fR is given only the \fIn\fR most recent events are printed or saved.
2765With \fB\-h\fR, the history list is printed without leading numbers. If
2766\fB-T\fR is specified, timestamps are printed also in comment form.
2767(This can be used to
2768produce files suitable for loading with 'history \-L' or 'source \-h'.)
2769With \fB\-r\fR, the order of printing is most recent
2770first rather than oldest first.
2771.PD
2772.RS +8
2773.PP
2774With \fB\-S\fR, the second form saves the history list to \fIfilename\fR.
2775If the first word of the \fBsavehist\fR shell variable is set to a
2776number, at most that many lines are saved. If the second word of
2777\fBsavehist\fR is set to `merge', the history list is merged with the
2778existing history file instead of replacing it (if there is one) and
2779sorted by time stamp. (+) Merging is intended for an environment like
2780the X Window System
2781with several shells in simultaneous use. Currently it succeeds
2782only when the shells quit nicely one after another.
2783.PP
2784With \fB\-L\fR, the shell appends \fIfilename\fR, which is presumably a
2785history list saved by the \fB\-S\fR option or the \fBsavehist\fR mechanism,
2786to the history list.
2787\fB\-M\fR is like \fB\-L\fR, but the contents of \fIfilename\fR are merged
2788into the history list and sorted by timestamp.
2789In either case, \fBhistfile\fR is used if \fIfilename\fR is not given and
2790\fI~/.history\fR is used if \fBhistfile\fR is unset.
2791`history \-L' is exactly like 'source \-h' except that it does not require a
2792filename.
2793.PP
2794Note that login shells do the equivalent of `history \-L' on startup
2795and, if \fBsavehist\fR is set, `history \-S' before exiting.
2796Because only \fI~/.tcshrc\fR is normally sourced before \fI~/.history\fR,
2797\fBhistfile\fR should be set in \fI~/.tcshrc\fR rather than \fI~/.login\fR.
2798.PP
2799If \fBhistlit\fR is set, the first and second forms print and save the literal
2800(unexpanded) form of the history list.
2801.PP
2802The last form clears the history list.
2803.RE
2804.TP 8
2805.B hup \fR[\fIcommand\fR] \fR(+)
2806With \fIcommand\fR, runs \fIcommand\fR such that it will exit on a hangup
2807signal and arranges for the shell to send it a hangup signal when the shell
2808exits.
2809Note that commands may set their own response to hangups, overriding \fIhup\fR.
2810Without an argument (allowed in only a shell script), causes the shell to
2811exit on a hangup for the remainder of the script.
2812See also \fBSignal handling\fR and the \fInohup\fR builtin command.
2813.TP 8
2814.B if (\fIexpr\fB) \fIcommand
2815If \fIexpr\fR (an expression, as described under \fBExpressions\fR)
2816evaluates true, then \fIcommand\fR is executed.
2817Variable substitution on \fIcommand\fR happens early, at the same time it
2818does for the rest of the \fIif\fR command.
2819\fIcommand\fR must be a simple command, not an alias, a pipeline, a command list
2820or a parenthesized command list, but it may have arguments.
2821Input/output redirection occurs even if \fIexpr\fR is
2822false and \fIcommand\fR is thus \fInot\fR executed; this is a bug.
2823.PP
2824.B if (\fIexpr\fB) then
2825.br
2826\&...
2827.br
2828.B else if (\fIexpr2\fB) then
2829.br
2830\&...
2831.br
2832.B else
2833.br
2834\&...
2835.PD 0
2836.TP 8
2837.B endif
2838If the specified \fIexpr\fR is true then the commands to the
2839first \fIelse\fR are executed; otherwise if \fIexpr2\fR is true then
2840the commands to the second \fIelse\fR are executed, etc. Any
2841number of \fIelse-if\fR pairs are possible; only one \fIendif\fR is
2842needed. The \fIelse\fR part is likewise optional. (The words
2843\fIelse\fR and \fIendif\fR must appear at the beginning of input lines;
2844the \fIif\fR must appear alone on its input line or after an
2845\fIelse\fR.)
2846.PD
2847.TP 8
2848.B inlib \fIshared-library\fR ... (+)
2849Adds each \fIshared-library\fR to the current environment. There is no way
2850to remove a shared library. (Domain/OS only)
2851.TP 8
2852.B jobs \fR[\fB\-l\fR]
2853Lists the active jobs. With \fB\-l\fR, lists process
2854IDs in addition to the normal information. On TCF systems, prints
2855the site on which each job is executing.
2856.PP
|
2851.B kill \fR[\fB\-\fIsignal\fR] \fB%\fIjob\fR|\fIpid\fR ...
| |
2852.PD 0
2853.TP 8
| 2857.PD 0
2858.TP 8
|
| 2859.B kill \fR[\fB\-s \fIsignal\fR] \fB%\fIjob\fR|\fIpid\fR ...
2860.PD 0
2861.TP 8
|
2854.B kill \-l
| 2862.B kill \-l
|
2855The first form sends the specified \fIsignal\fR (or, if none is given,
2856the TERM (terminate) signal) to the specified jobs or processes.
| 2863The first and second forms sends the specified \fIsignal\fR (or, if none
2864is given, the TERM (terminate) signal) to the specified jobs or processes.
|
2857\fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
2858under \fBJobs\fR.
2859Signals are either given by number or by name (as given in
2860\fI/usr/include/signal.h\fR, stripped of the prefix `SIG').
2861There is no default \fIjob\fR; saying just `kill' does not send a signal
2862to the current job. If the signal being sent is TERM (terminate)
2863or HUP (hangup), then the job or process is sent a
2864CONT (continue) signal as well.
| 2865\fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
2866under \fBJobs\fR.
2867Signals are either given by number or by name (as given in
2868\fI/usr/include/signal.h\fR, stripped of the prefix `SIG').
2869There is no default \fIjob\fR; saying just `kill' does not send a signal
2870to the current job. If the signal being sent is TERM (terminate)
2871or HUP (hangup), then the job or process is sent a
2872CONT (continue) signal as well.
|
2865The second form lists the signal names.
| 2873The third form lists the signal names.
|
2866.PD
2867.ig \" Obsolete tcsh command
2868.TP 8
2869.B linedit \fR(+)
2870A synonym for the \fIecho\fR builtin command.
2871..
2872.TP 8
2873.B limit \fR[\fB\-h\fR] [\fIresource\fR [\fImaximum-use\fR]]
2874Limits the consumption by the current process and each
2875process it creates to not individually exceed \fImaximum-use\fR on
2876the specified \fIresource\fR. If no \fImaximum-use\fR is given, then
2877the current limit is printed; if no \fIresource\fR is given, then
2878all limitations are given. If the \fB\-h\fR flag is given, the
2879hard limits are used instead of the current limits. The
2880hard limits impose a ceiling on the values of the current
2881limits. Only the super-user may raise the hard limits, but
2882a user may lower or raise the current limits within the legal range.
2883.RS +8
2884.PP
2885Controllable resources currently include \fIcputime\fR (the
2886maximum number of cpu-seconds to be used by each process),
2887\fIfilesize\fR (the largest single file which can be created),
2888\fIdatasize\fR (the maximum growth of the data+stack region via
2889sbrk(2) beyond the end of the program text), \fIstacksize\fR (the
2890maximum size of the automatically-extended stack region),
2891\fIcoredumpsize\fR (the size of the largest core dump that will be created),
2892and \fImemoryuse\fR, the maximum amount of physical memory a process
2893may have allocated to it at a given time.
2894.PP
2895\fImaximum-use\fR may be given as a (floating point or
2896integer) number followed by a scale factor. For all limits
2897other than \fIcputime\fR the default scale is `k' or `kilobytes'
2898(1024 bytes); a scale factor of `m' or `megabytes' may also
2899be used. For \fIcputime\fR the default scaling is `seconds',
2900while `m' for minutes or `h' for hours, or a time of the
2901form `mm:ss' giving minutes and seconds may be used.
2902.PP
2903For both \fIresource\fR names and scale factors, unambiguous
2904prefixes of the names suffice.
2905.RE
2906.TP 8
2907.B log \fR(+)
2908Prints the \fBwatch\fR shell variable and reports on each user indicated
2909in \fBwatch\fR who is logged in, regardless of when they last logged in.
2910See also \fIwatchlog\fR.
2911.TP 8
2912.B login
2913Terminates a login shell, replacing it with an instance of
2914\fI/bin/login.\fR This is one way to log off, included for
2915compatibility with \fIsh\fR(1).
2916.TP 8
2917.B logout
2918Terminates a login shell. Especially useful if \fBignoreeof\fR is set.
2919.TP 8
2920.B ls\-F \fR[\-\fIswitch\fR ...] [\fIfile\fR ...] (+)
2921Lists files like `ls \-F', but much faster. It identifies each type of
2922special file in the listing with a special character:
2923.PP
2924.RS +8
2925.PD 0
2926.TP 4
2927/
2928Directory
2929.TP 4
2930*
2931Executable
2932.TP 4
2933#
2934Block device
2935.TP 4
2936%
2937Character device
2938.TP 4
2939|
2940Named pipe (systems with named pipes only)
2941.TP 4
2942=
2943Socket (systems with sockets only)
2944.TP 4
2945@
2946Symbolic link (systems with symbolic links only)
2947.TP 4
2948+
2949Hidden directory (AIX only) or context dependent (HP/UX only)
2950.TP 4
2951:
2952Network special (HP/UX only)
2953.PD
2954.PP
2955If the \fBlistlinks\fR shell variable is set, symbolic links are identified
2956in more detail (on only systems that have them, of course):
2957.PP
2958.PD 0
2959.TP 4
2960@
2961Symbolic link to a non-directory
2962.TP 4
2963>
2964Symbolic link to a directory
2965.TP 4
2966&
2967Symbolic link to nowhere
2968.PD
2969.PP
2970\fBlistlinks\fR also slows down \fIls\-F\fR and causes partitions holding
2971files pointed to by symbolic links to be mounted.
2972.PP
2973If the \fBlistflags\fR shell variable is set to `x', `a' or `A', or any
2974combination thereof (e.g., `xA'), they are used as flags to \fIls\-F\fR,
2975making it act like `ls \-xF', `ls \-Fa', `ls \-FA' or a combination
2976(e.g., `ls \-FxA').
2977On machines where `ls \-C' is not the default, \fIls\-F\fR acts like `ls \-CF',
2978unless \fBlistflags\fR contains an `x', in which case it acts like `ls \-xF'.
2979\fIls\-F\fR passes its arguments to \fIls\fR(1) if it is given any switches,
2980so `alias ls ls\-F' generally does the right thing.
2981.PP
2982The \fBls\-F\fR builtin can list files using different colors depending on the
2983filetype or extension. See the \fBcolor\fR \fItcsh\fR variable and the
2984\fBLS_COLORS\fR environment variable.
2985.RE
2986.PP
2987.B migrate \fR[\fB\-\fIsite\fR] \fIpid\fR|\fB%\fIjobid\fR ... (+)
2988.PD 0
2989.TP 8
2990.B migrate \-\fIsite\fR (+)
2991The first form migrates the process or job to the site specified or the
2992default site determined by the system path.
2993The second form is equivalent to `migrate \-\fIsite\fR $$': it migrates the
2994current process to the specified site. Migrating the shell
2995itself can cause unexpected behavior, because the shell
2996does not like to lose its tty. (TCF only)
2997.PD
2998.TP 8
2999.B newgrp \fR[\fB\-\fR] \fIgroup\fR (+)
3000Equivalent to `exec newgrp'; see \fInewgrp\fR(1).
3001Available only if the shell was so compiled;
3002see the \fBversion\fR shell variable.
3003.TP 8
3004.B nice \fR[\fB+\fInumber\fR] [\fIcommand\fR]
3005Sets the scheduling priority for the shell to \fInumber\fR, or, without
3006\fInumber\fR, to 4. With \fIcommand\fR, runs \fIcommand\fR at the appropriate
3007priority.
3008The greater the \fInumber\fR, the less cpu
3009the process gets. The super-user may specify negative
3010priority by using `nice \-number ...'. Command is always
3011executed in a sub-shell, and the restrictions placed on
3012commands in simple \fIif\fR statements apply.
3013.TP 8
3014.B nohup \fR[\fIcommand\fR]
3015With \fIcommand\fR, runs \fIcommand\fR such that it will ignore hangup signals.
3016Note that commands may set their own response to hangups, overriding \fInohup\fR.
3017Without an argument (allowed in only a shell script), causes the shell to
3018ignore hangups for the remainder of the script.
3019See also \fBSignal handling\fR and the \fIhup\fR builtin command.
3020.TP 8
3021.B notify \fR[\fB%\fIjob\fR ...]
3022Causes the shell to notify the user asynchronously when the status of any
3023of the specified jobs (or, without %\fIjob\fR, the current job) changes,
3024instead of waiting until the next prompt as is usual.
3025\fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
3026under \fBJobs\fR.
3027See also the \fBnotify\fR shell variable.
3028.TP 8
3029.B onintr \fR[\fB\-\fR|\fIlabel\fR]
3030Controls the action of the shell on interrupts. Without arguments,
3031restores the default action of the shell on interrupts,
3032which is to terminate shell scripts or to return to the
3033terminal command input level.
3034With `\-', causes all interrupts to be ignored.
3035With \fIlabel\fR, causes the shell to execute a `goto \fIlabel\fR'
3036when an interrupt is received or a child process terminates because it was
3037interrupted.
3038.IP "" 8
3039\fIonintr\fR is ignored if the shell is running detached and in system
3040startup files (see \fBFILES\fR), where interrupts are disabled anyway.
3041.TP 8
3042.B popd \fR[\fB\-p\fR] [\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR] \fR[\fB+\fIn\fR]
3043Without arguments, pops the directory stack and returns to the new top directory.
3044With a number `+\fIn\fR', discards the \fIn\fR'th entry in the stack.
3045.IP "" 8
3046Finally, all forms of \fIpopd\fR print the final directory stack,
3047just like \fIdirs\fR. The \fBpushdsilent\fR shell variable can be set to
3048prevent this and the \fB\-p\fR flag can be given to override \fBpushdsilent\fR.
3049The \fB\-l\fR, \fB\-n\fR and \fB\-v\fR flags have the same effect on \fIpopd\fR
3050as on \fIdirs\fR. (+)
3051.TP 8
3052.B printenv \fR[\fIname\fR] (+)
3053Prints the names and values of all environment variables or,
3054with \fIname\fR, the value of the environment variable \fIname\fR.
3055.TP 8
3056.B pushd \fR[\fB\-p\fR] [\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR] [\fIname\fR|\fB+\fIn\fR]
3057Without arguments, exchanges the top two elements of the directory stack.
3058If \fBpushdtohome\fR is set, \fIpushd\fR without arguments does `pushd ~',
3059like \fIcd\fR. (+)
3060With \fIname\fR, pushes the current working directory onto the directory
3061stack and changes to \fIname\fR.
3062If \fIname\fR is `\-' it is interpreted as the previous working directory
3063(see \fBFilename substitution\fR). (+)
3064If \fBdunique\fR is set, \fIpushd\fR removes any instances of \fIname\fR
3065from the stack before pushing it onto the stack. (+)
3066With a number `+\fIn\fR', rotates the \fIn\fRth element of the
3067directory stack around to be the top element and changes to it.
3068If \fBdextract\fR is set, however, `pushd +\fIn\fR' extracts the \fIn\fRth
3069directory, pushes it onto the top of the stack and changes to it. (+)
3070.IP "" 8
3071Finally, all forms of \fIpushd\fR print the final directory stack,
3072just like \fIdirs\fR. The \fBpushdsilent\fR shell variable can be set to
3073prevent this and the \fB\-p\fR flag can be given to override \fBpushdsilent\fR.
3074The \fB\-l\fR, \fB\-n\fR and \fB\-v\fR flags have the same effect on \fIpushd\fR
3075as on \fIdirs\fR. (+)
3076.TP 8
3077.B rehash
3078Causes the internal hash table of the contents of the
3079directories in the \fBpath\fR variable to be recomputed. This is
3080needed if new commands are added to directories in \fBpath\fR
3081while you are logged in. This should be necessary only if
3082you add commands to one of your own directories, or if a
3083systems programmer changes the contents of one of the
3084system directories. Also flushes the cache of home directories
3085built by tilde expansion.
3086.TP 8
3087.B repeat \fIcount command
3088The specified \fIcommand\fR,
3089which is subject to the same restrictions as the \fIcommand\fR
3090in the one line \fIif\fR statement above, is executed \fIcount\fR times.
3091I/O redirections occur exactly once, even if \fIcount\fR is 0.
3092.TP 8
3093.B rootnode //\fInodename \fR(+)
3094Changes the rootnode to //\fInodename\fR, so that `/' will be interpreted
3095as `//\fInodename\fR'. (Domain/OS only)
3096.PP
3097.B sched \fR(+)
3098.br
3099.B sched \fR[\fB+\fR]\fIhh:mm command\fR \fR(+)
3100.PD 0
3101.TP 8
3102.B sched \-\fIn\fR (+)
3103The first form prints the scheduled-event list.
3104The \fBsched\fR shell variable may be set to define the format in which
3105the scheduled-event list is printed.
3106The second form adds \fIcommand\fR to the scheduled-event list.
3107For example,
3108.PD
3109.RS +8
3110.IP "" 4
3111> sched 11:00 echo It\\'s eleven o\\'clock.
3112.PP
3113causes the shell to echo `It's eleven o'clock.' at 11 AM.
3114The time may be in 12-hour AM/PM format
3115.IP "" 4
3116> sched 5pm set prompt='[%h] It\\'s after 5; go home: >'
3117.PP
3118or may be relative to the current time:
3119.IP "" 4
3120> sched +2:15 /usr/lib/uucp/uucico \-r1 \-sother
3121.PP
3122A relative time specification may not use AM/PM format.
3123The third form removes item \fIn\fR from the event list:
3124.IP "" 4
3125> sched
3126.br
3127 1 Wed Apr 4 15:42 /usr/lib/uucp/uucico \-r1 \-sother
3128.br
3129 2 Wed Apr 4 17:00 set prompt=[%h] It's after 5; go home: >
3130.br
3131> sched \-2
3132.br
3133> sched
3134.br
3135 1 Wed Apr 4 15:42 /usr/lib/uucp/uucico \-r1 \-sother
3136.PP
3137A command in the scheduled-event list is executed just before the first
3138prompt is printed after the time when the command is scheduled.
3139It is possible to miss the exact time when the command is to be run, but
3140an overdue command will execute at the next prompt.
3141A command which comes due while the shell
3142is waiting for user input is executed immediately.
3143However, normal operation of an already-running command will not
3144be interrupted so that a scheduled-event list element may be run.
3145.PP
3146This mechanism is similar to, but not the same as, the \fIat\fR(1)
3147command on some Unix systems.
3148Its major disadvantage is that it may not run a command at exactly the
3149specified time.
3150Its major advantage is that because \fIsched\fR runs directly from
3151the shell, it has access to shell variables and other structures.
3152This provides a mechanism for changing one's working environment
3153based on the time of day.
3154.RE
3155.PP
3156.B set
3157.br
3158.B set \fIname\fR ...
3159.br
3160.B set \fIname\fR\fB=\fIword\fR ...
3161.br
3162.B set [\-r] [\-f|\-l] \fIname\fR\fB=(\fIwordlist\fB)\fR ... (+)
3163.br
3164.B set \fIname[index]\fR\fB=\fIword\fR ...
3165.br
3166.B set \-r \fR(+)
3167.br
3168.B set \-r \fIname\fR ... (+)
3169.PD 0
3170.TP 8
3171.B set \-r \fIname\fR\fB=\fIword\fR ... (+)
3172The first form of the command prints the value of all shell variables.
3173Variables which contain more than a single word print as a
3174parenthesized word list.
3175The second form sets \fIname\fR to the null string.
3176The third form sets \fIname\fR to the single \fIword\fR.
3177The fourth form sets \fIname\fR to the list of words in
3178\fIwordlist\fR. In all cases the value is command and filename expanded.
3179If \-r is specified, the value is set read-only. If \-f or \-l are
3180specified, set only unique words keeping their order.
3181\-f prefers the first occurrence of a word, and \-l the last.
3182The fifth form sets the \fIindex\fR'th component of name to \fIword\fR;
3183this component must already exist.
3184The sixth form lists only the names of all shell variables that are read-only.
3185The seventh form makes \fIname\fR read-only, whether or not it has a value.
3186The second form sets \fIname\fR to the null string.
3187The eighth form is the same as the third form, but
3188make \fIname\fR read-only at the same time.
3189.PD
3190.IP "" 8
3191These arguments can be repeated to set and/or make read-only multiple variables
3192in a single set command. Note, however, that variable expansion
3193happens for all arguments before any setting occurs. Note also that `=' can
3194be adjacent to both \fIname\fR and \fIword\fR or separated from both by
3195whitespace, but cannot be adjacent to only one or the other.
3196See also the \fIunset\fR builtin command.
3197.TP 8
3198.B setenv \fR[\fIname \fR[\fIvalue\fR]]
3199Without arguments, prints the names and values of all environment variables.
3200Given \fIname\fR, sets the environment variable \fIname\fR to \fIvalue\fR
3201or, without \fIvalue\fR, to the null string.
3202.TP 8
3203.B setpath \fIpath \fR(+)
3204Equivalent to \fIsetpath\fR(1). (Mach only)
3205.TP 8
3206.B setspath\fR LOCAL|\fIsite\fR|\fIcpu\fR ... (+)
3207Sets the system execution path. (TCF only)
3208.TP 8
3209.B settc \fIcap value \fR(+)
3210Tells the shell to believe that the terminal capability \fIcap\fR
3211(as defined in \fItermcap\fR(5)) has the value \fIvalue\fR.
3212No sanity checking is done.
3213Concept terminal users may have to `settc xn no' to get proper
3214wrapping at the rightmost column.
3215.TP 8
3216.B setty \fR[\fB\-d\fR|\fB\-q\fR|\fB\-x\fR] [\fB\-a\fR] [[\fB+\fR|\fB\-\fR]\fImode\fR] (+)
3217Controls which tty modes (see \fBTerminal management\fR)
3218the shell does not allow to change.
3219\fB\-d\fR, \fB\-q\fR or \fB\-x\fR tells \fIsetty\fR to act
3220on the `edit', `quote' or `execute' set of tty modes respectively; without
3221\fB\-d\fR, \fB\-q\fR or \fB\-x\fR, `execute' is used.
3222.IP "" 8
3223Without other arguments, \fIsetty\fR lists the modes in the chosen set
3224which are fixed on (`+mode') or off (`\-mode').
3225The available modes, and thus the display, vary from system to system.
3226With \fB\-a\fR, lists all tty modes in the chosen set
3227whether or not they are fixed.
3228With \fB+\fImode\fR, \fB\-\fImode\fR or \fImode\fR, fixes \fImode\fR on or off
3229or removes control from \fImode\fR in the chosen set.
3230For example, `setty +echok echoe' fixes `echok' mode on and allows commands
3231to turn `echoe' mode on or off, both when the shell is executing commands.
3232.TP 8
3233.B setxvers\fR [\fIstring\fR] (+)
3234Set the experimental version prefix to \fIstring\fR, or removes it
3235if \fIstring\fR is omitted. (TCF only)
3236.TP 8
3237.B shift \fR[\fIvariable\fR]
3238Without arguments, discards \fBargv\fR[1] and shifts the members of
3239\fBargv\fR to the left. It is an error for \fBargv\fR not to be set or to have
3240less than one word as value. With \fIvariable\fR, performs the
3241same function on \fIvariable\fR.
3242.TP 8
3243.B source \fR[\fB\-h\fR] \fIname\fR [\fIargs\fR ...]
3244The shell reads and executes commands from \fIname\fR.
3245The commands are not placed on the history list.
3246If any \fIargs\fR are given, they are placed in \fBargv\fR. (+)
3247\fIsource\fR commands may be nested;
3248if they are nested too deeply the shell may run out of file descriptors.
3249An error in a \fIsource\fR at any level terminates all nested
3250\fIsource\fR commands.
3251With \fB\-h\fR, commands are placed on the history list instead of being
3252executed, much like `history \-L'.
3253.TP 8
3254.B stop \fB%\fIjob\fR|\fIpid\fR ...
3255Stops the specified jobs or processes which are executing in the background.
3256\fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
3257under \fBJobs\fR.
3258There is no default \fIjob\fR; saying just `stop' does not stop
3259the current job.
3260.TP 8
3261.B suspend
3262Causes the shell to stop in its tracks, much as if it had
3263been sent a stop signal with \fB^Z\fR. This is most often used to
3264stop shells started by \fIsu\fR(1).
3265.PP
3266.B switch (\fIstring\fB)
3267.br
3268.B case \fIstr1\fB:
3269.PD 0
3270.IP "" 4
3271\&...
3272.br
3273.B breaksw
3274.PP
3275\&...
3276.PP
3277.B default:
3278.IP "" 4
3279\&...
3280.br
3281.B breaksw
3282.TP 8
3283.B endsw
3284Each case label is successively matched, against the
3285specified \fIstring\fR which is first command and filename expanded.
3286The file metacharacters `*', `?' and `[...]' may be used
3287in the case labels, which are variable expanded. If none
3288of the labels match before a `default' label is found, then
3289the execution begins after the default label. Each case
3290label and the default label must appear at the beginning of
3291a line. The command \fIbreaksw\fR causes execution to continue
3292after the \fIendsw\fR. Otherwise control may fall through case
3293labels and default labels as in C. If no label matches and
3294there is no default, execution continues after the \fIendsw\fR.
3295.PD
3296.TP 8
3297.B telltc \fR(+)
3298Lists the values of all terminal capabilities (see \fItermcap\fR(5)).
3299.TP 8
3300.B time \fR[\fIcommand\fR]
3301Executes \fIcommand\fR (which must be a simple command, not an alias,
3302a pipeline, a command list or a parenthesized command list)
3303and prints a time summary as described under the \fBtime\fR variable.
3304If necessary, an extra shell is created to print the time statistic when
3305the command completes.
3306Without \fIcommand\fR, prints a time summary for the current shell and its
3307children.
3308.TP 8
3309.B umask \fR[\fIvalue\fR]
3310Sets the file creation mask to \fIvalue\fR, which is given in octal.
3311Common values for the mask are
3312002, giving all access to the group and read and execute access to others, and
3313022, giving read and execute access to the group and others.
3314Without \fIvalue\fR, prints the current file creation mask.
3315.TP 8
3316.B unalias \fIpattern
3317.br
3318Removes all aliases whose names match \fIpattern\fR.
3319`unalias *' thus removes all aliases.
3320It is not an error for nothing to be \fIunalias\fRed.
3321.TP 8
3322.B uncomplete \fIpattern\fR (+)
3323Removes all completions whose names match \fIpattern\fR.
3324`uncomplete *' thus removes all completions.
3325It is not an error for nothing to be \fIuncomplete\fRd.
3326.TP 8
3327.B unhash
3328Disables use of the internal hash table to speed location of
3329executed programs.
3330.TP 8
3331.B universe \fIuniverse\fR (+)
3332Sets the universe to \fIuniverse\fR. (Masscomp/RTU only)
3333.TP 8
3334.B unlimit \fR[\fB\-h\fR] [\fIresource\fR]
3335Removes the limitation on \fIresource\fR or, if no \fIresource\fR is
3336specified, all \fIresource\fR limitations.
3337With \fB\-h\fR, the corresponding hard limits are removed.
3338Only the super-user may do this.
3339.TP 8
3340.B unset \fIpattern
3341Removes all variables whose names match \fIpattern\fR, unless they are read-only.
3342`unset *' thus removes all variables unless they are read-only;
3343this is a bad idea.
3344It is not an error for nothing to be \fIunset\fR.
3345.TP 8
3346.B unsetenv \fIpattern
3347Removes all environment variables whose names match \fIpattern\fR.
3348`unsetenv *' thus removes all environment variables;
3349this is a bad idea.
3350It is not an error for nothing to be \fIunsetenv\fRed.
3351.TP 8
3352.B ver \fR[\fIsystype\fR [\fIcommand\fR]] (+)
3353Without arguments, prints \fBSYSTYPE\fR. With \fIsystype\fR, sets \fBSYSTYPE\fR
3354to \fIsystype\fR. With \fIsystype\fR and \fIcommand\fR, executes \fIcommand\fR
3355under \fIsystype\fR. \fIsystype\fR may be `bsd4.3' or `sys5.3'.
3356(Domain/OS only)
3357.TP 8
3358.B wait
3359The shell waits for all background jobs. If the shell is interactive, an
3360interrupt will disrupt the wait and cause the shell to print the names and job
3361numbers of all outstanding jobs.
3362.TP 8
3363.B warp \fIuniverse\fR (+)
3364Sets the universe to \fIuniverse\fR. (Convex/OS only)
3365.TP 8
3366.B watchlog \fR(+)
3367An alternate name for the \fIlog\fR builtin command (q.v.).
3368Available only if the shell was so compiled;
3369see the \fBversion\fR shell variable.
3370.TP 8
3371.B where \fIcommand\fR (+)
3372Reports all known instances of \fIcommand\fR, including aliases, builtins and
3373executables in \fBpath\fR.
3374.TP 8
3375.B which\fR \fIcommand\fR (+)
3376Displays the command that will be executed by the shell after substitutions,
3377\fBpath\fR searching, etc.
3378The builtin command is just like \fIwhich\fR(1), but it correctly reports
3379\fItcsh\fR aliases and builtins and is 10 to 100 times faster.
3380See also the \fIwhich-command\fR editor command.
3381.PP
3382.B while (\fIexpr\fB)\fR
3383.br
3384\&...
3385.PD 0
3386.TP 8
3387.B end
3388Executes the commands between the \fIwhile\fR and the matching \fIend\fR
3389while \fIexpr\fR (an expression, as described under \fBExpressions\fR)
3390evaluates non-zero.
3391\fIwhile\fR and \fIend\fR must appear alone on their input lines.
3392\fIbreak\fR and \fIcontinue\fR may be used to terminate or continue the
3393loop prematurely.
3394If the input is a terminal, the user is prompted the first time
3395through the loop as with \fIforeach\fR.
3396.PD
3397.SS "Special aliases (+)"
3398If set, each of these aliases executes automatically at the indicated time.
3399They are all initially undefined.
3400.TP 8
3401.B beepcmd
3402Runs when the shell wants to ring the terminal bell.
3403.TP 8
3404.B cwdcmd
3405Runs after every change of working directory. For example, if the user is
3406working on an X window system using \fIxterm\fR(1) and a re-parenting window
3407manager that supports title bars such as \fItwm\fR(1) and does
3408.RS +8
3409.IP "" 4
3410> alias cwdcmd 'echo \-n "^[]2;${HOST}:$cwd ^G"'
3411.PP
3412then the shell will change the title of the running \fIxterm\fR(1)
3413to be the name of the host, a colon, and the full current working directory.
3414A fancier way to do that is
3415.IP "" 4
3416> alias cwdcmd 'echo \-n "^[]2;${HOST}:$cwd^G^[]1;${HOST}^G"'
3417.PP
3418This will put the hostname and working directory on the title bar but
3419only the hostname in the icon manager menu.
3420.PP
3421Note that putting a \fIcd\fR, \fIpushd\fR or \fIpopd\fR in \fIcwdcmd\fR
3422may cause an infinite loop. It is the author's opinion that anyone doing
3423so will get what they deserve.
3424.RE
3425.TP 8
| 2874.PD
2875.ig \" Obsolete tcsh command
2876.TP 8
2877.B linedit \fR(+)
2878A synonym for the \fIecho\fR builtin command.
2879..
2880.TP 8
2881.B limit \fR[\fB\-h\fR] [\fIresource\fR [\fImaximum-use\fR]]
2882Limits the consumption by the current process and each
2883process it creates to not individually exceed \fImaximum-use\fR on
2884the specified \fIresource\fR. If no \fImaximum-use\fR is given, then
2885the current limit is printed; if no \fIresource\fR is given, then
2886all limitations are given. If the \fB\-h\fR flag is given, the
2887hard limits are used instead of the current limits. The
2888hard limits impose a ceiling on the values of the current
2889limits. Only the super-user may raise the hard limits, but
2890a user may lower or raise the current limits within the legal range.
2891.RS +8
2892.PP
2893Controllable resources currently include \fIcputime\fR (the
2894maximum number of cpu-seconds to be used by each process),
2895\fIfilesize\fR (the largest single file which can be created),
2896\fIdatasize\fR (the maximum growth of the data+stack region via
2897sbrk(2) beyond the end of the program text), \fIstacksize\fR (the
2898maximum size of the automatically-extended stack region),
2899\fIcoredumpsize\fR (the size of the largest core dump that will be created),
2900and \fImemoryuse\fR, the maximum amount of physical memory a process
2901may have allocated to it at a given time.
2902.PP
2903\fImaximum-use\fR may be given as a (floating point or
2904integer) number followed by a scale factor. For all limits
2905other than \fIcputime\fR the default scale is `k' or `kilobytes'
2906(1024 bytes); a scale factor of `m' or `megabytes' may also
2907be used. For \fIcputime\fR the default scaling is `seconds',
2908while `m' for minutes or `h' for hours, or a time of the
2909form `mm:ss' giving minutes and seconds may be used.
2910.PP
2911For both \fIresource\fR names and scale factors, unambiguous
2912prefixes of the names suffice.
2913.RE
2914.TP 8
2915.B log \fR(+)
2916Prints the \fBwatch\fR shell variable and reports on each user indicated
2917in \fBwatch\fR who is logged in, regardless of when they last logged in.
2918See also \fIwatchlog\fR.
2919.TP 8
2920.B login
2921Terminates a login shell, replacing it with an instance of
2922\fI/bin/login.\fR This is one way to log off, included for
2923compatibility with \fIsh\fR(1).
2924.TP 8
2925.B logout
2926Terminates a login shell. Especially useful if \fBignoreeof\fR is set.
2927.TP 8
2928.B ls\-F \fR[\-\fIswitch\fR ...] [\fIfile\fR ...] (+)
2929Lists files like `ls \-F', but much faster. It identifies each type of
2930special file in the listing with a special character:
2931.PP
2932.RS +8
2933.PD 0
2934.TP 4
2935/
2936Directory
2937.TP 4
2938*
2939Executable
2940.TP 4
2941#
2942Block device
2943.TP 4
2944%
2945Character device
2946.TP 4
2947|
2948Named pipe (systems with named pipes only)
2949.TP 4
2950=
2951Socket (systems with sockets only)
2952.TP 4
2953@
2954Symbolic link (systems with symbolic links only)
2955.TP 4
2956+
2957Hidden directory (AIX only) or context dependent (HP/UX only)
2958.TP 4
2959:
2960Network special (HP/UX only)
2961.PD
2962.PP
2963If the \fBlistlinks\fR shell variable is set, symbolic links are identified
2964in more detail (on only systems that have them, of course):
2965.PP
2966.PD 0
2967.TP 4
2968@
2969Symbolic link to a non-directory
2970.TP 4
2971>
2972Symbolic link to a directory
2973.TP 4
2974&
2975Symbolic link to nowhere
2976.PD
2977.PP
2978\fBlistlinks\fR also slows down \fIls\-F\fR and causes partitions holding
2979files pointed to by symbolic links to be mounted.
2980.PP
2981If the \fBlistflags\fR shell variable is set to `x', `a' or `A', or any
2982combination thereof (e.g., `xA'), they are used as flags to \fIls\-F\fR,
2983making it act like `ls \-xF', `ls \-Fa', `ls \-FA' or a combination
2984(e.g., `ls \-FxA').
2985On machines where `ls \-C' is not the default, \fIls\-F\fR acts like `ls \-CF',
2986unless \fBlistflags\fR contains an `x', in which case it acts like `ls \-xF'.
2987\fIls\-F\fR passes its arguments to \fIls\fR(1) if it is given any switches,
2988so `alias ls ls\-F' generally does the right thing.
2989.PP
2990The \fBls\-F\fR builtin can list files using different colors depending on the
2991filetype or extension. See the \fBcolor\fR \fItcsh\fR variable and the
2992\fBLS_COLORS\fR environment variable.
2993.RE
2994.PP
2995.B migrate \fR[\fB\-\fIsite\fR] \fIpid\fR|\fB%\fIjobid\fR ... (+)
2996.PD 0
2997.TP 8
2998.B migrate \-\fIsite\fR (+)
2999The first form migrates the process or job to the site specified or the
3000default site determined by the system path.
3001The second form is equivalent to `migrate \-\fIsite\fR $$': it migrates the
3002current process to the specified site. Migrating the shell
3003itself can cause unexpected behavior, because the shell
3004does not like to lose its tty. (TCF only)
3005.PD
3006.TP 8
3007.B newgrp \fR[\fB\-\fR] \fIgroup\fR (+)
3008Equivalent to `exec newgrp'; see \fInewgrp\fR(1).
3009Available only if the shell was so compiled;
3010see the \fBversion\fR shell variable.
3011.TP 8
3012.B nice \fR[\fB+\fInumber\fR] [\fIcommand\fR]
3013Sets the scheduling priority for the shell to \fInumber\fR, or, without
3014\fInumber\fR, to 4. With \fIcommand\fR, runs \fIcommand\fR at the appropriate
3015priority.
3016The greater the \fInumber\fR, the less cpu
3017the process gets. The super-user may specify negative
3018priority by using `nice \-number ...'. Command is always
3019executed in a sub-shell, and the restrictions placed on
3020commands in simple \fIif\fR statements apply.
3021.TP 8
3022.B nohup \fR[\fIcommand\fR]
3023With \fIcommand\fR, runs \fIcommand\fR such that it will ignore hangup signals.
3024Note that commands may set their own response to hangups, overriding \fInohup\fR.
3025Without an argument (allowed in only a shell script), causes the shell to
3026ignore hangups for the remainder of the script.
3027See also \fBSignal handling\fR and the \fIhup\fR builtin command.
3028.TP 8
3029.B notify \fR[\fB%\fIjob\fR ...]
3030Causes the shell to notify the user asynchronously when the status of any
3031of the specified jobs (or, without %\fIjob\fR, the current job) changes,
3032instead of waiting until the next prompt as is usual.
3033\fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
3034under \fBJobs\fR.
3035See also the \fBnotify\fR shell variable.
3036.TP 8
3037.B onintr \fR[\fB\-\fR|\fIlabel\fR]
3038Controls the action of the shell on interrupts. Without arguments,
3039restores the default action of the shell on interrupts,
3040which is to terminate shell scripts or to return to the
3041terminal command input level.
3042With `\-', causes all interrupts to be ignored.
3043With \fIlabel\fR, causes the shell to execute a `goto \fIlabel\fR'
3044when an interrupt is received or a child process terminates because it was
3045interrupted.
3046.IP "" 8
3047\fIonintr\fR is ignored if the shell is running detached and in system
3048startup files (see \fBFILES\fR), where interrupts are disabled anyway.
3049.TP 8
3050.B popd \fR[\fB\-p\fR] [\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR] \fR[\fB+\fIn\fR]
3051Without arguments, pops the directory stack and returns to the new top directory.
3052With a number `+\fIn\fR', discards the \fIn\fR'th entry in the stack.
3053.IP "" 8
3054Finally, all forms of \fIpopd\fR print the final directory stack,
3055just like \fIdirs\fR. The \fBpushdsilent\fR shell variable can be set to
3056prevent this and the \fB\-p\fR flag can be given to override \fBpushdsilent\fR.
3057The \fB\-l\fR, \fB\-n\fR and \fB\-v\fR flags have the same effect on \fIpopd\fR
3058as on \fIdirs\fR. (+)
3059.TP 8
3060.B printenv \fR[\fIname\fR] (+)
3061Prints the names and values of all environment variables or,
3062with \fIname\fR, the value of the environment variable \fIname\fR.
3063.TP 8
3064.B pushd \fR[\fB\-p\fR] [\fB\-l\fR] [\fB\-n\fR|\fB\-v\fR] [\fIname\fR|\fB+\fIn\fR]
3065Without arguments, exchanges the top two elements of the directory stack.
3066If \fBpushdtohome\fR is set, \fIpushd\fR without arguments does `pushd ~',
3067like \fIcd\fR. (+)
3068With \fIname\fR, pushes the current working directory onto the directory
3069stack and changes to \fIname\fR.
3070If \fIname\fR is `\-' it is interpreted as the previous working directory
3071(see \fBFilename substitution\fR). (+)
3072If \fBdunique\fR is set, \fIpushd\fR removes any instances of \fIname\fR
3073from the stack before pushing it onto the stack. (+)
3074With a number `+\fIn\fR', rotates the \fIn\fRth element of the
3075directory stack around to be the top element and changes to it.
3076If \fBdextract\fR is set, however, `pushd +\fIn\fR' extracts the \fIn\fRth
3077directory, pushes it onto the top of the stack and changes to it. (+)
3078.IP "" 8
3079Finally, all forms of \fIpushd\fR print the final directory stack,
3080just like \fIdirs\fR. The \fBpushdsilent\fR shell variable can be set to
3081prevent this and the \fB\-p\fR flag can be given to override \fBpushdsilent\fR.
3082The \fB\-l\fR, \fB\-n\fR and \fB\-v\fR flags have the same effect on \fIpushd\fR
3083as on \fIdirs\fR. (+)
3084.TP 8
3085.B rehash
3086Causes the internal hash table of the contents of the
3087directories in the \fBpath\fR variable to be recomputed. This is
3088needed if new commands are added to directories in \fBpath\fR
3089while you are logged in. This should be necessary only if
3090you add commands to one of your own directories, or if a
3091systems programmer changes the contents of one of the
3092system directories. Also flushes the cache of home directories
3093built by tilde expansion.
3094.TP 8
3095.B repeat \fIcount command
3096The specified \fIcommand\fR,
3097which is subject to the same restrictions as the \fIcommand\fR
3098in the one line \fIif\fR statement above, is executed \fIcount\fR times.
3099I/O redirections occur exactly once, even if \fIcount\fR is 0.
3100.TP 8
3101.B rootnode //\fInodename \fR(+)
3102Changes the rootnode to //\fInodename\fR, so that `/' will be interpreted
3103as `//\fInodename\fR'. (Domain/OS only)
3104.PP
3105.B sched \fR(+)
3106.br
3107.B sched \fR[\fB+\fR]\fIhh:mm command\fR \fR(+)
3108.PD 0
3109.TP 8
3110.B sched \-\fIn\fR (+)
3111The first form prints the scheduled-event list.
3112The \fBsched\fR shell variable may be set to define the format in which
3113the scheduled-event list is printed.
3114The second form adds \fIcommand\fR to the scheduled-event list.
3115For example,
3116.PD
3117.RS +8
3118.IP "" 4
3119> sched 11:00 echo It\\'s eleven o\\'clock.
3120.PP
3121causes the shell to echo `It's eleven o'clock.' at 11 AM.
3122The time may be in 12-hour AM/PM format
3123.IP "" 4
3124> sched 5pm set prompt='[%h] It\\'s after 5; go home: >'
3125.PP
3126or may be relative to the current time:
3127.IP "" 4
3128> sched +2:15 /usr/lib/uucp/uucico \-r1 \-sother
3129.PP
3130A relative time specification may not use AM/PM format.
3131The third form removes item \fIn\fR from the event list:
3132.IP "" 4
3133> sched
3134.br
3135 1 Wed Apr 4 15:42 /usr/lib/uucp/uucico \-r1 \-sother
3136.br
3137 2 Wed Apr 4 17:00 set prompt=[%h] It's after 5; go home: >
3138.br
3139> sched \-2
3140.br
3141> sched
3142.br
3143 1 Wed Apr 4 15:42 /usr/lib/uucp/uucico \-r1 \-sother
3144.PP
3145A command in the scheduled-event list is executed just before the first
3146prompt is printed after the time when the command is scheduled.
3147It is possible to miss the exact time when the command is to be run, but
3148an overdue command will execute at the next prompt.
3149A command which comes due while the shell
3150is waiting for user input is executed immediately.
3151However, normal operation of an already-running command will not
3152be interrupted so that a scheduled-event list element may be run.
3153.PP
3154This mechanism is similar to, but not the same as, the \fIat\fR(1)
3155command on some Unix systems.
3156Its major disadvantage is that it may not run a command at exactly the
3157specified time.
3158Its major advantage is that because \fIsched\fR runs directly from
3159the shell, it has access to shell variables and other structures.
3160This provides a mechanism for changing one's working environment
3161based on the time of day.
3162.RE
3163.PP
3164.B set
3165.br
3166.B set \fIname\fR ...
3167.br
3168.B set \fIname\fR\fB=\fIword\fR ...
3169.br
3170.B set [\-r] [\-f|\-l] \fIname\fR\fB=(\fIwordlist\fB)\fR ... (+)
3171.br
3172.B set \fIname[index]\fR\fB=\fIword\fR ...
3173.br
3174.B set \-r \fR(+)
3175.br
3176.B set \-r \fIname\fR ... (+)
3177.PD 0
3178.TP 8
3179.B set \-r \fIname\fR\fB=\fIword\fR ... (+)
3180The first form of the command prints the value of all shell variables.
3181Variables which contain more than a single word print as a
3182parenthesized word list.
3183The second form sets \fIname\fR to the null string.
3184The third form sets \fIname\fR to the single \fIword\fR.
3185The fourth form sets \fIname\fR to the list of words in
3186\fIwordlist\fR. In all cases the value is command and filename expanded.
3187If \-r is specified, the value is set read-only. If \-f or \-l are
3188specified, set only unique words keeping their order.
3189\-f prefers the first occurrence of a word, and \-l the last.
3190The fifth form sets the \fIindex\fR'th component of name to \fIword\fR;
3191this component must already exist.
3192The sixth form lists only the names of all shell variables that are read-only.
3193The seventh form makes \fIname\fR read-only, whether or not it has a value.
3194The second form sets \fIname\fR to the null string.
3195The eighth form is the same as the third form, but
3196make \fIname\fR read-only at the same time.
3197.PD
3198.IP "" 8
3199These arguments can be repeated to set and/or make read-only multiple variables
3200in a single set command. Note, however, that variable expansion
3201happens for all arguments before any setting occurs. Note also that `=' can
3202be adjacent to both \fIname\fR and \fIword\fR or separated from both by
3203whitespace, but cannot be adjacent to only one or the other.
3204See also the \fIunset\fR builtin command.
3205.TP 8
3206.B setenv \fR[\fIname \fR[\fIvalue\fR]]
3207Without arguments, prints the names and values of all environment variables.
3208Given \fIname\fR, sets the environment variable \fIname\fR to \fIvalue\fR
3209or, without \fIvalue\fR, to the null string.
3210.TP 8
3211.B setpath \fIpath \fR(+)
3212Equivalent to \fIsetpath\fR(1). (Mach only)
3213.TP 8
3214.B setspath\fR LOCAL|\fIsite\fR|\fIcpu\fR ... (+)
3215Sets the system execution path. (TCF only)
3216.TP 8
3217.B settc \fIcap value \fR(+)
3218Tells the shell to believe that the terminal capability \fIcap\fR
3219(as defined in \fItermcap\fR(5)) has the value \fIvalue\fR.
3220No sanity checking is done.
3221Concept terminal users may have to `settc xn no' to get proper
3222wrapping at the rightmost column.
3223.TP 8
3224.B setty \fR[\fB\-d\fR|\fB\-q\fR|\fB\-x\fR] [\fB\-a\fR] [[\fB+\fR|\fB\-\fR]\fImode\fR] (+)
3225Controls which tty modes (see \fBTerminal management\fR)
3226the shell does not allow to change.
3227\fB\-d\fR, \fB\-q\fR or \fB\-x\fR tells \fIsetty\fR to act
3228on the `edit', `quote' or `execute' set of tty modes respectively; without
3229\fB\-d\fR, \fB\-q\fR or \fB\-x\fR, `execute' is used.
3230.IP "" 8
3231Without other arguments, \fIsetty\fR lists the modes in the chosen set
3232which are fixed on (`+mode') or off (`\-mode').
3233The available modes, and thus the display, vary from system to system.
3234With \fB\-a\fR, lists all tty modes in the chosen set
3235whether or not they are fixed.
3236With \fB+\fImode\fR, \fB\-\fImode\fR or \fImode\fR, fixes \fImode\fR on or off
3237or removes control from \fImode\fR in the chosen set.
3238For example, `setty +echok echoe' fixes `echok' mode on and allows commands
3239to turn `echoe' mode on or off, both when the shell is executing commands.
3240.TP 8
3241.B setxvers\fR [\fIstring\fR] (+)
3242Set the experimental version prefix to \fIstring\fR, or removes it
3243if \fIstring\fR is omitted. (TCF only)
3244.TP 8
3245.B shift \fR[\fIvariable\fR]
3246Without arguments, discards \fBargv\fR[1] and shifts the members of
3247\fBargv\fR to the left. It is an error for \fBargv\fR not to be set or to have
3248less than one word as value. With \fIvariable\fR, performs the
3249same function on \fIvariable\fR.
3250.TP 8
3251.B source \fR[\fB\-h\fR] \fIname\fR [\fIargs\fR ...]
3252The shell reads and executes commands from \fIname\fR.
3253The commands are not placed on the history list.
3254If any \fIargs\fR are given, they are placed in \fBargv\fR. (+)
3255\fIsource\fR commands may be nested;
3256if they are nested too deeply the shell may run out of file descriptors.
3257An error in a \fIsource\fR at any level terminates all nested
3258\fIsource\fR commands.
3259With \fB\-h\fR, commands are placed on the history list instead of being
3260executed, much like `history \-L'.
3261.TP 8
3262.B stop \fB%\fIjob\fR|\fIpid\fR ...
3263Stops the specified jobs or processes which are executing in the background.
3264\fIjob\fR may be a number, a string, `', `%', `+' or `\-' as described
3265under \fBJobs\fR.
3266There is no default \fIjob\fR; saying just `stop' does not stop
3267the current job.
3268.TP 8
3269.B suspend
3270Causes the shell to stop in its tracks, much as if it had
3271been sent a stop signal with \fB^Z\fR. This is most often used to
3272stop shells started by \fIsu\fR(1).
3273.PP
3274.B switch (\fIstring\fB)
3275.br
3276.B case \fIstr1\fB:
3277.PD 0
3278.IP "" 4
3279\&...
3280.br
3281.B breaksw
3282.PP
3283\&...
3284.PP
3285.B default:
3286.IP "" 4
3287\&...
3288.br
3289.B breaksw
3290.TP 8
3291.B endsw
3292Each case label is successively matched, against the
3293specified \fIstring\fR which is first command and filename expanded.
3294The file metacharacters `*', `?' and `[...]' may be used
3295in the case labels, which are variable expanded. If none
3296of the labels match before a `default' label is found, then
3297the execution begins after the default label. Each case
3298label and the default label must appear at the beginning of
3299a line. The command \fIbreaksw\fR causes execution to continue
3300after the \fIendsw\fR. Otherwise control may fall through case
3301labels and default labels as in C. If no label matches and
3302there is no default, execution continues after the \fIendsw\fR.
3303.PD
3304.TP 8
3305.B telltc \fR(+)
3306Lists the values of all terminal capabilities (see \fItermcap\fR(5)).
3307.TP 8
3308.B time \fR[\fIcommand\fR]
3309Executes \fIcommand\fR (which must be a simple command, not an alias,
3310a pipeline, a command list or a parenthesized command list)
3311and prints a time summary as described under the \fBtime\fR variable.
3312If necessary, an extra shell is created to print the time statistic when
3313the command completes.
3314Without \fIcommand\fR, prints a time summary for the current shell and its
3315children.
3316.TP 8
3317.B umask \fR[\fIvalue\fR]
3318Sets the file creation mask to \fIvalue\fR, which is given in octal.
3319Common values for the mask are
3320002, giving all access to the group and read and execute access to others, and
3321022, giving read and execute access to the group and others.
3322Without \fIvalue\fR, prints the current file creation mask.
3323.TP 8
3324.B unalias \fIpattern
3325.br
3326Removes all aliases whose names match \fIpattern\fR.
3327`unalias *' thus removes all aliases.
3328It is not an error for nothing to be \fIunalias\fRed.
3329.TP 8
3330.B uncomplete \fIpattern\fR (+)
3331Removes all completions whose names match \fIpattern\fR.
3332`uncomplete *' thus removes all completions.
3333It is not an error for nothing to be \fIuncomplete\fRd.
3334.TP 8
3335.B unhash
3336Disables use of the internal hash table to speed location of
3337executed programs.
3338.TP 8
3339.B universe \fIuniverse\fR (+)
3340Sets the universe to \fIuniverse\fR. (Masscomp/RTU only)
3341.TP 8
3342.B unlimit \fR[\fB\-h\fR] [\fIresource\fR]
3343Removes the limitation on \fIresource\fR or, if no \fIresource\fR is
3344specified, all \fIresource\fR limitations.
3345With \fB\-h\fR, the corresponding hard limits are removed.
3346Only the super-user may do this.
3347.TP 8
3348.B unset \fIpattern
3349Removes all variables whose names match \fIpattern\fR, unless they are read-only.
3350`unset *' thus removes all variables unless they are read-only;
3351this is a bad idea.
3352It is not an error for nothing to be \fIunset\fR.
3353.TP 8
3354.B unsetenv \fIpattern
3355Removes all environment variables whose names match \fIpattern\fR.
3356`unsetenv *' thus removes all environment variables;
3357this is a bad idea.
3358It is not an error for nothing to be \fIunsetenv\fRed.
3359.TP 8
3360.B ver \fR[\fIsystype\fR [\fIcommand\fR]] (+)
3361Without arguments, prints \fBSYSTYPE\fR. With \fIsystype\fR, sets \fBSYSTYPE\fR
3362to \fIsystype\fR. With \fIsystype\fR and \fIcommand\fR, executes \fIcommand\fR
3363under \fIsystype\fR. \fIsystype\fR may be `bsd4.3' or `sys5.3'.
3364(Domain/OS only)
3365.TP 8
3366.B wait
3367The shell waits for all background jobs. If the shell is interactive, an
3368interrupt will disrupt the wait and cause the shell to print the names and job
3369numbers of all outstanding jobs.
3370.TP 8
3371.B warp \fIuniverse\fR (+)
3372Sets the universe to \fIuniverse\fR. (Convex/OS only)
3373.TP 8
3374.B watchlog \fR(+)
3375An alternate name for the \fIlog\fR builtin command (q.v.).
3376Available only if the shell was so compiled;
3377see the \fBversion\fR shell variable.
3378.TP 8
3379.B where \fIcommand\fR (+)
3380Reports all known instances of \fIcommand\fR, including aliases, builtins and
3381executables in \fBpath\fR.
3382.TP 8
3383.B which\fR \fIcommand\fR (+)
3384Displays the command that will be executed by the shell after substitutions,
3385\fBpath\fR searching, etc.
3386The builtin command is just like \fIwhich\fR(1), but it correctly reports
3387\fItcsh\fR aliases and builtins and is 10 to 100 times faster.
3388See also the \fIwhich-command\fR editor command.
3389.PP
3390.B while (\fIexpr\fB)\fR
3391.br
3392\&...
3393.PD 0
3394.TP 8
3395.B end
3396Executes the commands between the \fIwhile\fR and the matching \fIend\fR
3397while \fIexpr\fR (an expression, as described under \fBExpressions\fR)
3398evaluates non-zero.
3399\fIwhile\fR and \fIend\fR must appear alone on their input lines.
3400\fIbreak\fR and \fIcontinue\fR may be used to terminate or continue the
3401loop prematurely.
3402If the input is a terminal, the user is prompted the first time
3403through the loop as with \fIforeach\fR.
3404.PD
3405.SS "Special aliases (+)"
3406If set, each of these aliases executes automatically at the indicated time.
3407They are all initially undefined.
3408.TP 8
3409.B beepcmd
3410Runs when the shell wants to ring the terminal bell.
3411.TP 8
3412.B cwdcmd
3413Runs after every change of working directory. For example, if the user is
3414working on an X window system using \fIxterm\fR(1) and a re-parenting window
3415manager that supports title bars such as \fItwm\fR(1) and does
3416.RS +8
3417.IP "" 4
3418> alias cwdcmd 'echo \-n "^[]2;${HOST}:$cwd ^G"'
3419.PP
3420then the shell will change the title of the running \fIxterm\fR(1)
3421to be the name of the host, a colon, and the full current working directory.
3422A fancier way to do that is
3423.IP "" 4
3424> alias cwdcmd 'echo \-n "^[]2;${HOST}:$cwd^G^[]1;${HOST}^G"'
3425.PP
3426This will put the hostname and working directory on the title bar but
3427only the hostname in the icon manager menu.
3428.PP
3429Note that putting a \fIcd\fR, \fIpushd\fR or \fIpopd\fR in \fIcwdcmd\fR
3430may cause an infinite loop. It is the author's opinion that anyone doing
3431so will get what they deserve.
3432.RE
3433.TP 8
|
| 3434.B jobcmd
3435Runs before each command gets executed, or when the command changes state.
3436This is similar to \fIpostcmd\fR, but it does not print builtins.
3437.RS +8
3438.IP "" 4
3439> alias jobcmd 'echo \-n "^[]2\e;\e!#^G"'
3440.PP
3441then executing \fIvi foo.c\fR will put the command string in the xterm title bar.
3442.RE
3443.TP 8
|
3426.B helpcommand
3427Invoked by the \fBrun-help\fR editor command. The command name for which help
3428is sought is passed as sole argument.
3429For example, if one does
3430.RS +8
3431.IP "" 4
3432> alias helpcommand '\e!:1 --help'
3433.PP
3434then the help display of the command itself will be invoked, using the GNU
3435help calling convention.
3436Currently there is no easy way to account for various calling conventions (e.g.,
3437the customary Unix `-h'), except by using a table of many commands.
3438.RE
3439.TP 8
3440.B periodic
3441Runs every \fBtperiod\fR minutes. This provides a convenient means for
3442checking on common but infrequent changes such as new mail. For example,
3443if one does
3444.RS +8
3445.IP "" 4
3446> set tperiod = 30
3447.br
3448> alias periodic checknews
3449.PP
3450then the \fIchecknews\fR(1) program runs every 30 minutes.
3451If \fIperiodic\fR is set but \fBtperiod\fR is unset or set to 0,
3452\fIperiodic\fR behaves like \fIprecmd\fR.
3453.RE
3454.TP 8
3455.B precmd
3456Runs just before each prompt is printed. For example, if one does
3457.RS +8
3458.IP "" 4
3459> alias precmd date
3460.PP
3461then \fIdate\fR(1) runs just before the shell prompts for each command.
3462There are no limits on what \fIprecmd\fR can be set to do, but discretion
3463should be used.
3464.RE
3465.TP 8
3466.B postcmd
3467Runs before each command gets executed.
3468.RS +8
3469.IP "" 4
3470> alias postcmd 'echo \-n "^[]2\e;\e!#^G"'
3471.PP
3472then executing \fIvi foo.c\fR will put the command string in the xterm title bar.
3473.RE
3474.TP 8
3475.B shell
3476Specifies the interpreter for executable scripts which do not themselves
3477specify an interpreter. The first word should be a full path name to the
3478desired interpreter (e.g., `/bin/csh' or `/usr/local/bin/tcsh').
3479.SS "Special shell variables"
3480The variables described in this section have special meaning to the shell.
3481.PP
3482The shell sets \fBaddsuffix\fR, \fBargv\fR, \fBautologout\fR, \fBcommand\fR, \fBecho_style\fR,
3483\fBedit\fR, \fBgid\fR, \fBgroup\fR, \fBhome\fR, \fBloginsh\fR, \fBoid\fR, \fBpath\fR,
3484\fBprompt\fR, \fBprompt2\fR, \fBprompt3\fR, \fBshell\fR, \fBshlvl\fR,
3485\fBtcsh\fR, \fBterm\fR, \fBtty\fR, \fBuid\fR, \fBuser\fR and \fBversion\fR at
3486startup; they do not change thereafter unless changed by the user. The shell
3487updates \fBcwd\fR, \fBdirstack\fR, \fBowd\fR and \fBstatus\fR when necessary,
3488and sets \fBlogout\fR on logout.
3489.PP
3490The shell synchronizes \fBafsuser\fR, \fBgroup\fR, \fBhome\fR, \fBpath\fR, \fBshlvl\fR,
3491\fBterm\fR and \fBuser\fR with the environment variables of the same names:
3492whenever the environment variable changes the shell changes the corresponding
3493shell variable to match (unless the shell variable is read-only) and vice
3494versa. Note that although \fBcwd\fR and \fBPWD\fR have identical meanings, they
3495are not synchronized in this manner, and that the shell automatically
3496interconverts the different formats of \fBpath\fR and \fBPATH\fR.
3497.TP 8
3498.B addsuffix \fR(+)
3499If set, filename completion adds `/' to the end of directories and a space
3500to the end of normal files when they are matched exactly.
3501Set by default.
3502.TP 8
3503.B afsuser \fR(+)
3504If set, \fBautologout\fR's autolock feature uses its value instead of
3505the local username for kerberos authentication.
3506.TP 8
3507.B ampm \fR(+)
3508If set, all times are shown in 12-hour AM/PM format.
3509.TP 8
3510.B argv
3511The arguments to the shell. Positional parameters are taken from \fBargv\fR,
3512i.e., `$1' is replaced by `$argv[1]', etc.
3513Set by default, but usually empty in interactive shells.
3514.TP 8
3515.B autocorrect \fR(+)
3516If set, the \fIspell-word\fR editor command is invoked automatically before
3517each completion attempt.
3518.TP 8
3519.B autoexpand \fR(+)
3520If set, the \fIexpand-history\fR editor command is invoked automatically
3521before each completion attempt.
3522.TP 8
3523.B autolist \fR(+)
3524If set, possibilities are listed after an ambiguous completion.
3525If set to `ambiguous', possibilities are listed only when no new
3526characters are added by completion.
3527.TP 8
3528.B autologout \fR(+)
3529The first word is the number of minutes of inactivity before automatic
3530logout. The optional second word is the number of minutes of inactivity
3531before automatic locking.
3532When the shell automatically logs out,
3533it prints `auto-logout', sets the variable logout to `automatic' and exits.
3534When the shell automatically locks, the user is required to enter his password
3535to continue working. Five incorrect attempts result in automatic logout.
3536Set to `60' (automatic logout after 60 minutes, and no locking) by default
3537in login and superuser shells, but not if the shell thinks it is running
3538under a window system (i.e., the \fBDISPLAY\fR environment variable is set),
3539the tty is a pseudo-tty (pty) or the shell was not so compiled (see the
3540\fBversion\fR shell variable).
3541See also the \fBafsuser\fR and \fBlogout\fR shell variables.
3542.TP 8
3543.B backslash_quote \fR(+)
3544If set, backslashes (`\\') always quote `\\', `'', and `"'. This may make
3545complex quoting tasks easier, but it can cause syntax errors in \fIcsh\fR(1)
3546scripts.
3547.TP 8
3548.B catalog
3549The file name of the message catalog.
3550If set, tcsh use `tcsh.${catalog}' as a message catalog instead of
3551default `tcsh'.
3552.TP 8
3553.B cdpath
3554A list of directories in which \fIcd\fR should search for
3555subdirectories if they aren't found in the current directory.
3556.TP 8
3557.B color
3558If set, it enables color display for the builtin \fBls\-F\fR and it passes
3559\fB\-\-color=auto\fR to \fBls\fR. Alternatively, it can be set to only
3560\fBls\-F\fR or only \fBls\fR to enable color to only one command. Setting
3561it to nothing is equivalent to setting it to \fB(ls\-F ls)\fR.
3562.TP 8
3563.B colorcat
3564If set, it enables color escape sequence for NLS message files.
3565And display colorful NLS messages.
3566.TP 8
3567.B command \fR(+)
3568If set, the command which was passed to the shell with the \fB-c\fR flag (q.v.).
3569.TP 8
3570.B complete \fR(+)
3571If set to `enhance', completion 1) ignores case and 2) considers
3572periods, hyphens and underscores (`.', `\-' and `_') to be word
3573separators and hyphens and underscores to be equivalent.
3574.TP 8
3575.B continue \fR(+)
3576If set to a list of commands, the shell will continue the listed
3577commands, instead of starting a new one.
3578.TP 8
3579.B continue_args \fR(+)
3580Same as continue, but the shell will execute:
3581.RS +8
3582.IP "" 4
3583echo `pwd` $argv > ~/.<cmd>_pause; %<cmd>
3584.RE
3585.TP 8
3586.B correct \fR(+)
3587If set to `cmd', commands are automatically spelling-corrected.
3588If set to `complete', commands are automatically completed.
3589If set to `all', the entire command line is corrected.
3590.TP 8
3591.B cwd
3592The full pathname of the current directory.
3593See also the \fBdirstack\fR and \fBowd\fR shell variables.
3594.TP 8
3595.B dextract \fR(+)
3596If set, `pushd +\fIn\fR' extracts the \fIn\fRth directory from the directory
3597stack rather than rotating it to the top.
3598.TP 8
3599.B dirsfile \fR(+)
3600The default location in which `dirs \-S' and `dirs \-L' look for
3601a history file. If unset, \fI~/.cshdirs\fR is used.
3602Because only \fI~/.tcshrc\fR is normally sourced before \fI~/.cshdirs\fR,
3603\fBdirsfile\fR should be set in \fI~/.tcshrc\fR rather than \fI~/.login\fR.
3604.TP 8
3605.B dirstack \fR(+)
3606An array of all the directories on the directory stack.
3607`$dirstack[1]' is the current working directory, `$dirstack[2]'
3608the first directory on the stack, etc.
3609Note that the current working directory is `$dirstack[1]' but `=0' in
3610directory stack substitutions, etc.
3611One can change the stack arbitrarily by setting \fBdirstack\fR,
3612but the first element (the current working directory) is always correct.
3613See also the \fBcwd\fR and \fBowd\fR shell variables.
3614.TP 8
3615.B dspmbyte \fR(+)
3616If set to `euc', it enables display and editing EUC-kanji(Japanese) code.
3617If set to `sjis', it enables display and editing Shift-JIS(Japanese) code.
| 3444.B helpcommand
3445Invoked by the \fBrun-help\fR editor command. The command name for which help
3446is sought is passed as sole argument.
3447For example, if one does
3448.RS +8
3449.IP "" 4
3450> alias helpcommand '\e!:1 --help'
3451.PP
3452then the help display of the command itself will be invoked, using the GNU
3453help calling convention.
3454Currently there is no easy way to account for various calling conventions (e.g.,
3455the customary Unix `-h'), except by using a table of many commands.
3456.RE
3457.TP 8
3458.B periodic
3459Runs every \fBtperiod\fR minutes. This provides a convenient means for
3460checking on common but infrequent changes such as new mail. For example,
3461if one does
3462.RS +8
3463.IP "" 4
3464> set tperiod = 30
3465.br
3466> alias periodic checknews
3467.PP
3468then the \fIchecknews\fR(1) program runs every 30 minutes.
3469If \fIperiodic\fR is set but \fBtperiod\fR is unset or set to 0,
3470\fIperiodic\fR behaves like \fIprecmd\fR.
3471.RE
3472.TP 8
3473.B precmd
3474Runs just before each prompt is printed. For example, if one does
3475.RS +8
3476.IP "" 4
3477> alias precmd date
3478.PP
3479then \fIdate\fR(1) runs just before the shell prompts for each command.
3480There are no limits on what \fIprecmd\fR can be set to do, but discretion
3481should be used.
3482.RE
3483.TP 8
3484.B postcmd
3485Runs before each command gets executed.
3486.RS +8
3487.IP "" 4
3488> alias postcmd 'echo \-n "^[]2\e;\e!#^G"'
3489.PP
3490then executing \fIvi foo.c\fR will put the command string in the xterm title bar.
3491.RE
3492.TP 8
3493.B shell
3494Specifies the interpreter for executable scripts which do not themselves
3495specify an interpreter. The first word should be a full path name to the
3496desired interpreter (e.g., `/bin/csh' or `/usr/local/bin/tcsh').
3497.SS "Special shell variables"
3498The variables described in this section have special meaning to the shell.
3499.PP
3500The shell sets \fBaddsuffix\fR, \fBargv\fR, \fBautologout\fR, \fBcommand\fR, \fBecho_style\fR,
3501\fBedit\fR, \fBgid\fR, \fBgroup\fR, \fBhome\fR, \fBloginsh\fR, \fBoid\fR, \fBpath\fR,
3502\fBprompt\fR, \fBprompt2\fR, \fBprompt3\fR, \fBshell\fR, \fBshlvl\fR,
3503\fBtcsh\fR, \fBterm\fR, \fBtty\fR, \fBuid\fR, \fBuser\fR and \fBversion\fR at
3504startup; they do not change thereafter unless changed by the user. The shell
3505updates \fBcwd\fR, \fBdirstack\fR, \fBowd\fR and \fBstatus\fR when necessary,
3506and sets \fBlogout\fR on logout.
3507.PP
3508The shell synchronizes \fBafsuser\fR, \fBgroup\fR, \fBhome\fR, \fBpath\fR, \fBshlvl\fR,
3509\fBterm\fR and \fBuser\fR with the environment variables of the same names:
3510whenever the environment variable changes the shell changes the corresponding
3511shell variable to match (unless the shell variable is read-only) and vice
3512versa. Note that although \fBcwd\fR and \fBPWD\fR have identical meanings, they
3513are not synchronized in this manner, and that the shell automatically
3514interconverts the different formats of \fBpath\fR and \fBPATH\fR.
3515.TP 8
3516.B addsuffix \fR(+)
3517If set, filename completion adds `/' to the end of directories and a space
3518to the end of normal files when they are matched exactly.
3519Set by default.
3520.TP 8
3521.B afsuser \fR(+)
3522If set, \fBautologout\fR's autolock feature uses its value instead of
3523the local username for kerberos authentication.
3524.TP 8
3525.B ampm \fR(+)
3526If set, all times are shown in 12-hour AM/PM format.
3527.TP 8
3528.B argv
3529The arguments to the shell. Positional parameters are taken from \fBargv\fR,
3530i.e., `$1' is replaced by `$argv[1]', etc.
3531Set by default, but usually empty in interactive shells.
3532.TP 8
3533.B autocorrect \fR(+)
3534If set, the \fIspell-word\fR editor command is invoked automatically before
3535each completion attempt.
3536.TP 8
3537.B autoexpand \fR(+)
3538If set, the \fIexpand-history\fR editor command is invoked automatically
3539before each completion attempt.
3540.TP 8
3541.B autolist \fR(+)
3542If set, possibilities are listed after an ambiguous completion.
3543If set to `ambiguous', possibilities are listed only when no new
3544characters are added by completion.
3545.TP 8
3546.B autologout \fR(+)
3547The first word is the number of minutes of inactivity before automatic
3548logout. The optional second word is the number of minutes of inactivity
3549before automatic locking.
3550When the shell automatically logs out,
3551it prints `auto-logout', sets the variable logout to `automatic' and exits.
3552When the shell automatically locks, the user is required to enter his password
3553to continue working. Five incorrect attempts result in automatic logout.
3554Set to `60' (automatic logout after 60 minutes, and no locking) by default
3555in login and superuser shells, but not if the shell thinks it is running
3556under a window system (i.e., the \fBDISPLAY\fR environment variable is set),
3557the tty is a pseudo-tty (pty) or the shell was not so compiled (see the
3558\fBversion\fR shell variable).
3559See also the \fBafsuser\fR and \fBlogout\fR shell variables.
3560.TP 8
3561.B backslash_quote \fR(+)
3562If set, backslashes (`\\') always quote `\\', `'', and `"'. This may make
3563complex quoting tasks easier, but it can cause syntax errors in \fIcsh\fR(1)
3564scripts.
3565.TP 8
3566.B catalog
3567The file name of the message catalog.
3568If set, tcsh use `tcsh.${catalog}' as a message catalog instead of
3569default `tcsh'.
3570.TP 8
3571.B cdpath
3572A list of directories in which \fIcd\fR should search for
3573subdirectories if they aren't found in the current directory.
3574.TP 8
3575.B color
3576If set, it enables color display for the builtin \fBls\-F\fR and it passes
3577\fB\-\-color=auto\fR to \fBls\fR. Alternatively, it can be set to only
3578\fBls\-F\fR or only \fBls\fR to enable color to only one command. Setting
3579it to nothing is equivalent to setting it to \fB(ls\-F ls)\fR.
3580.TP 8
3581.B colorcat
3582If set, it enables color escape sequence for NLS message files.
3583And display colorful NLS messages.
3584.TP 8
3585.B command \fR(+)
3586If set, the command which was passed to the shell with the \fB-c\fR flag (q.v.).
3587.TP 8
3588.B complete \fR(+)
3589If set to `enhance', completion 1) ignores case and 2) considers
3590periods, hyphens and underscores (`.', `\-' and `_') to be word
3591separators and hyphens and underscores to be equivalent.
3592.TP 8
3593.B continue \fR(+)
3594If set to a list of commands, the shell will continue the listed
3595commands, instead of starting a new one.
3596.TP 8
3597.B continue_args \fR(+)
3598Same as continue, but the shell will execute:
3599.RS +8
3600.IP "" 4
3601echo `pwd` $argv > ~/.<cmd>_pause; %<cmd>
3602.RE
3603.TP 8
3604.B correct \fR(+)
3605If set to `cmd', commands are automatically spelling-corrected.
3606If set to `complete', commands are automatically completed.
3607If set to `all', the entire command line is corrected.
3608.TP 8
3609.B cwd
3610The full pathname of the current directory.
3611See also the \fBdirstack\fR and \fBowd\fR shell variables.
3612.TP 8
3613.B dextract \fR(+)
3614If set, `pushd +\fIn\fR' extracts the \fIn\fRth directory from the directory
3615stack rather than rotating it to the top.
3616.TP 8
3617.B dirsfile \fR(+)
3618The default location in which `dirs \-S' and `dirs \-L' look for
3619a history file. If unset, \fI~/.cshdirs\fR is used.
3620Because only \fI~/.tcshrc\fR is normally sourced before \fI~/.cshdirs\fR,
3621\fBdirsfile\fR should be set in \fI~/.tcshrc\fR rather than \fI~/.login\fR.
3622.TP 8
3623.B dirstack \fR(+)
3624An array of all the directories on the directory stack.
3625`$dirstack[1]' is the current working directory, `$dirstack[2]'
3626the first directory on the stack, etc.
3627Note that the current working directory is `$dirstack[1]' but `=0' in
3628directory stack substitutions, etc.
3629One can change the stack arbitrarily by setting \fBdirstack\fR,
3630but the first element (the current working directory) is always correct.
3631See also the \fBcwd\fR and \fBowd\fR shell variables.
3632.TP 8
3633.B dspmbyte \fR(+)
3634If set to `euc', it enables display and editing EUC-kanji(Japanese) code.
3635If set to `sjis', it enables display and editing Shift-JIS(Japanese) code.
|
| 3636If set to `big5', it enables display and editing Big5(Chinese) code.
|
3618If set to the following format, it enables display and editing of original
3619multi-byte code format:
3620.RS +8
3621.IP "" 4
3622> set dspmbyte = 0000....(256 bytes)....0000
3623.PP
3624The table requires \fBjust\fR 256 bytes. Each character of 256 characters
3625corresponds (from left to right) to the ASCII codes 0x00, 0x01, ... 0xff. Each
3626character
3627.\" (position in this table?)
3628is set to number 0,1,2 and 3. Each number has the following meaning:
3629.br
3630 0 ... not used for multi-byte characters.
3631.br
3632 1 ... used for the first byte of a multi-byte character.
3633.br
3634 2 ... used for the second byte of a multi-byte character.
3635.br
3636 3 ... used for both the first byte and second byte of a multi-byte character.
3637.\" SHK: I tried my best to get the following to be grammatically correct.
3638.\" However, I still don't understand what's going on here. In the
3639 \" following example, there are three bytes, but the text seems to refer to
3640 \" each nybble as a character. What's going on here? It this 3-byte code
3641 \" in the table? The text above seems to imply that there are 256
3642 \" characters/bytes in the table. If I get some more info on this (perhaps
3643 \" a complete example), I could fix the text to be grammatically correct.
3644 \" (steve.kelem@xilinx.com 1999/09/13)
3645.PP
3646 Example:
3647.br
3648If set to `001322', the first character (means 0x00 of the ASCII code) and
3649second character (means 0x01 of ASCII code) are set to `0'. Then, it is not
3650used for multi-byte characters. The 3rd character (0x02) is set to '2',
3651indicating that it is used for the first byte of a multi-byte character.
3652The 4th character(0x03) is set '3'. It is used for both the first byte and
3653the second byte of a multi-byte character. The 5th and 6th characters
3654(0x04,0x05) are set to '2', indicating that they are used for the second
3655byte of a multi-byte character.
3656.PP
3657The GNU fileutils version of ls cannot display multi-byte
3658filenames without the -N ( --literal ) option. If you are using
3659this version, set the second word of dspmbyte to "ls". If not, for
3660example, "ls-F -l" cannot display multi-byte filenames.
3661.RE
3662.TP 8
3663.B dunique \fR(+)
3664If set, \fIpushd\fR removes any instances of \fIname\fR
3665from the stack before pushing it onto the stack.
3666.TP 8
3667.B echo
3668If set, each command with its arguments is echoed just before it is
3669executed. For non-builtin commands all expansions occur before
3670echoing. Builtin commands are echoed before command and filename
3671substitution, because these substitutions are then done selectively.
3672Set by the \fB\-x\fR command line option.
3673.TP 8
3674.B echo_style \fR(+)
3675The style of the \fIecho\fR builtin. May be set to
3676.PP
3677.RS +8
3678.PD 0
3679.TP 8
3680bsd
3681Don't echo a newline if the first argument is `\-n'.
3682.TP 8
3683sysv
3684Recognize backslashed escape sequences in echo strings.
3685.TP 8
3686both
3687Recognize both the `\-n' flag and backslashed escape sequences; the default.
3688.TP 8
3689none
3690Recognize neither.
3691.PD
3692.PP
3693Set by default to the local system default. The BSD and System V
3694options are described in the \fIecho\fR(1) man pages on the appropriate
3695systems.
3696.RE
3697.TP 8
3698.B edit \fR(+)
3699If set, the command-line editor is used. Set by default in interactive
3700shells.
3701.TP 8
3702.B ellipsis \fR(+)
3703If set, the `%c'/`%.' and `%C' prompt sequences (see the \fBprompt\fR
3704shell variable) indicate skipped directories with an ellipsis (`...')
3705instead of `/<skipped>'.
3706.TP 8
3707.B fignore \fR(+)
3708Lists file name suffixes to be ignored by completion.
3709.TP 8
3710.B filec
3711In \fItcsh\fR, completion is always used and this variable is ignored.
3712If set in \fIcsh\fR, filename completion is used.
3713.TP 8
3714.B gid \fR(+)
3715The user's real group ID.
3716.TP 8
3717.B group \fR(+)
3718The user's group name.
3719.TP 8
3720.B histchars
3721A string value determining the characters used in \fBHistory
3722substitution\fR (q.v.). The first character of its value is used as
3723the history substitution character, replacing the default character
3724`!'. The second character of its value replaces the character `^' in
3725quick substitutions.
3726.TP 8
3727.B histdup \fR(+)
3728Controls handling of duplicate entries in the history list. If set to
3729`all' only unique history events are entered in the history list. If
3730set to `prev' and the last history event is the same as the current
3731command, then the current command is not entered in the history. If
3732set to `erase' and the same event is found in the history list, that
3733old event gets erased and the current one gets inserted. Note that the
3734`prev' and `all' options renumber history events so there are no gaps.
3735.TP 8
3736.B histfile \fR(+)
3737The default location in which `history \-S' and `history \-L' look for
3738a history file. If unset, \fI~/.history\fR is used. \fBhistfile\fR is
3739useful when sharing the same home directory between different machines,
3740or when saving separate histories on different terminals. Because only
3741\fI~/.tcshrc\fR is normally sourced before \fI~/.history\fR,
3742\fBhistfile\fR should be set in \fI~/.tcshrc\fR rather than
3743\fI~/.login\fR.
3744.TP 8
3745.B histlit \fR(+)
3746If set, builtin and editor commands and the \fBsavehist\fR mechanism
3747use the literal (unexpanded) form of lines in the history list. See
3748also the \fItoggle-literal-history\fR editor command.
3749.TP 8
3750.B history
3751The first word indicates the number of history events to save. The
3752optional second word (+) indicates the format in which history is
3753printed; if not given, `%h\\t%T\\t%R\\n' is used. The format sequences
3754are described below under \fBprompt\fR; note the variable meaning of
3755`%R'. Set to `100' by default.
3756.TP 8
3757.B home
3758Initialized to the home directory of the invoker. The filename
3759expansion of `\fI~\fR' refers to this variable.
3760.TP 8
3761.B ignoreeof
3762If set to the empty string or `0' and the input device is a terminal,
3763the \fIend-of-file\fR command (usually generated by the user by typing
3764`^D' on an empty line) causes the shell to print `Use "exit" to leave
3765tcsh.' instead of exiting. This prevents the shell from accidentally
3766being killed. If set to a number \fIn\fR, the shell ignores \fIn\fR -
37671 consecutive \fIend-of-file\fRs and exits on the \fIn\fRth. (+) If
3768unset, `1' is used, i.e., the shell exits on a single `^D'.
3769.TP 8
3770.B implicitcd \fR(+)
3771If set, the shell treats a directory name typed as a command as though
3772it were a request to change to that directory. If set to \fIverbose\fR,
3773the change of directory is echoed to the standard output. This behavior
3774is inhibited in non-interactive shell scripts, or for command strings
3775with more than one word. Changing directory takes precedence over
3776executing a like-named command, but it is done after alias
3777substitutions. Tilde and variable expansions work as expected.
3778.TP 8
3779.B inputmode \fR(+)
3780If set to `insert' or `overwrite', puts the editor into that input mode
3781at the beginning of each line.
3782.TP 8
| 3637If set to the following format, it enables display and editing of original
3638multi-byte code format:
3639.RS +8
3640.IP "" 4
3641> set dspmbyte = 0000....(256 bytes)....0000
3642.PP
3643The table requires \fBjust\fR 256 bytes. Each character of 256 characters
3644corresponds (from left to right) to the ASCII codes 0x00, 0x01, ... 0xff. Each
3645character
3646.\" (position in this table?)
3647is set to number 0,1,2 and 3. Each number has the following meaning:
3648.br
3649 0 ... not used for multi-byte characters.
3650.br
3651 1 ... used for the first byte of a multi-byte character.
3652.br
3653 2 ... used for the second byte of a multi-byte character.
3654.br
3655 3 ... used for both the first byte and second byte of a multi-byte character.
3656.\" SHK: I tried my best to get the following to be grammatically correct.
3657.\" However, I still don't understand what's going on here. In the
3658 \" following example, there are three bytes, but the text seems to refer to
3659 \" each nybble as a character. What's going on here? It this 3-byte code
3660 \" in the table? The text above seems to imply that there are 256
3661 \" characters/bytes in the table. If I get some more info on this (perhaps
3662 \" a complete example), I could fix the text to be grammatically correct.
3663 \" (steve.kelem@xilinx.com 1999/09/13)
3664.PP
3665 Example:
3666.br
3667If set to `001322', the first character (means 0x00 of the ASCII code) and
3668second character (means 0x01 of ASCII code) are set to `0'. Then, it is not
3669used for multi-byte characters. The 3rd character (0x02) is set to '2',
3670indicating that it is used for the first byte of a multi-byte character.
3671The 4th character(0x03) is set '3'. It is used for both the first byte and
3672the second byte of a multi-byte character. The 5th and 6th characters
3673(0x04,0x05) are set to '2', indicating that they are used for the second
3674byte of a multi-byte character.
3675.PP
3676The GNU fileutils version of ls cannot display multi-byte
3677filenames without the -N ( --literal ) option. If you are using
3678this version, set the second word of dspmbyte to "ls". If not, for
3679example, "ls-F -l" cannot display multi-byte filenames.
3680.RE
3681.TP 8
3682.B dunique \fR(+)
3683If set, \fIpushd\fR removes any instances of \fIname\fR
3684from the stack before pushing it onto the stack.
3685.TP 8
3686.B echo
3687If set, each command with its arguments is echoed just before it is
3688executed. For non-builtin commands all expansions occur before
3689echoing. Builtin commands are echoed before command and filename
3690substitution, because these substitutions are then done selectively.
3691Set by the \fB\-x\fR command line option.
3692.TP 8
3693.B echo_style \fR(+)
3694The style of the \fIecho\fR builtin. May be set to
3695.PP
3696.RS +8
3697.PD 0
3698.TP 8
3699bsd
3700Don't echo a newline if the first argument is `\-n'.
3701.TP 8
3702sysv
3703Recognize backslashed escape sequences in echo strings.
3704.TP 8
3705both
3706Recognize both the `\-n' flag and backslashed escape sequences; the default.
3707.TP 8
3708none
3709Recognize neither.
3710.PD
3711.PP
3712Set by default to the local system default. The BSD and System V
3713options are described in the \fIecho\fR(1) man pages on the appropriate
3714systems.
3715.RE
3716.TP 8
3717.B edit \fR(+)
3718If set, the command-line editor is used. Set by default in interactive
3719shells.
3720.TP 8
3721.B ellipsis \fR(+)
3722If set, the `%c'/`%.' and `%C' prompt sequences (see the \fBprompt\fR
3723shell variable) indicate skipped directories with an ellipsis (`...')
3724instead of `/<skipped>'.
3725.TP 8
3726.B fignore \fR(+)
3727Lists file name suffixes to be ignored by completion.
3728.TP 8
3729.B filec
3730In \fItcsh\fR, completion is always used and this variable is ignored.
3731If set in \fIcsh\fR, filename completion is used.
3732.TP 8
3733.B gid \fR(+)
3734The user's real group ID.
3735.TP 8
3736.B group \fR(+)
3737The user's group name.
3738.TP 8
3739.B histchars
3740A string value determining the characters used in \fBHistory
3741substitution\fR (q.v.). The first character of its value is used as
3742the history substitution character, replacing the default character
3743`!'. The second character of its value replaces the character `^' in
3744quick substitutions.
3745.TP 8
3746.B histdup \fR(+)
3747Controls handling of duplicate entries in the history list. If set to
3748`all' only unique history events are entered in the history list. If
3749set to `prev' and the last history event is the same as the current
3750command, then the current command is not entered in the history. If
3751set to `erase' and the same event is found in the history list, that
3752old event gets erased and the current one gets inserted. Note that the
3753`prev' and `all' options renumber history events so there are no gaps.
3754.TP 8
3755.B histfile \fR(+)
3756The default location in which `history \-S' and `history \-L' look for
3757a history file. If unset, \fI~/.history\fR is used. \fBhistfile\fR is
3758useful when sharing the same home directory between different machines,
3759or when saving separate histories on different terminals. Because only
3760\fI~/.tcshrc\fR is normally sourced before \fI~/.history\fR,
3761\fBhistfile\fR should be set in \fI~/.tcshrc\fR rather than
3762\fI~/.login\fR.
3763.TP 8
3764.B histlit \fR(+)
3765If set, builtin and editor commands and the \fBsavehist\fR mechanism
3766use the literal (unexpanded) form of lines in the history list. See
3767also the \fItoggle-literal-history\fR editor command.
3768.TP 8
3769.B history
3770The first word indicates the number of history events to save. The
3771optional second word (+) indicates the format in which history is
3772printed; if not given, `%h\\t%T\\t%R\\n' is used. The format sequences
3773are described below under \fBprompt\fR; note the variable meaning of
3774`%R'. Set to `100' by default.
3775.TP 8
3776.B home
3777Initialized to the home directory of the invoker. The filename
3778expansion of `\fI~\fR' refers to this variable.
3779.TP 8
3780.B ignoreeof
3781If set to the empty string or `0' and the input device is a terminal,
3782the \fIend-of-file\fR command (usually generated by the user by typing
3783`^D' on an empty line) causes the shell to print `Use "exit" to leave
3784tcsh.' instead of exiting. This prevents the shell from accidentally
3785being killed. If set to a number \fIn\fR, the shell ignores \fIn\fR -
37861 consecutive \fIend-of-file\fRs and exits on the \fIn\fRth. (+) If
3787unset, `1' is used, i.e., the shell exits on a single `^D'.
3788.TP 8
3789.B implicitcd \fR(+)
3790If set, the shell treats a directory name typed as a command as though
3791it were a request to change to that directory. If set to \fIverbose\fR,
3792the change of directory is echoed to the standard output. This behavior
3793is inhibited in non-interactive shell scripts, or for command strings
3794with more than one word. Changing directory takes precedence over
3795executing a like-named command, but it is done after alias
3796substitutions. Tilde and variable expansions work as expected.
3797.TP 8
3798.B inputmode \fR(+)
3799If set to `insert' or `overwrite', puts the editor into that input mode
3800at the beginning of each line.
3801.TP 8
|
| 3802.B killdup \fR(+)
3803Controls handling of duplicate entries in the kill ring. If set to
3804`all' only unique strings are entered in the kill ring. If set to
3805`prev' and the last killed string is the same as the current killed
3806string, then the current string is not entered in the ring. If set
3807to `erase' and the same string is found in the kill ring, the old
3808string is erased and the current one is inserted.
3809.TP 8
3810.B killring \fR(+)
3811Indicates the number of killed strings to keep in memory. Set to `30'
3812by default. If unset or set to less than `2', the shell will only
3813keep the most recently killed string.
3814.TP 8
|
3783.B listflags \fR(+)
3784If set to `x', `a' or `A', or any combination thereof (e.g., `xA'), they
3785are used as flags to \fIls\-F\fR, making it act like `ls \-xF', `ls
3786\-Fa', `ls \-FA' or a combination (e.g., `ls \-FxA'): `a' shows all
3787files (even if they start with a `.'), `A' shows all files but `.' and
3788`..', and `x' sorts across instead of down. If the second word of
3789\fBlistflags\fR is set, it is used as the path to `ls(1)'.
3790.TP 8
3791.B listjobs \fR(+)
3792If set, all jobs are listed when a job is suspended. If set to `long',
3793the listing is in long format.
3794.TP 8
3795.B listlinks \fR(+)
3796If set, the \fIls\-F\fR builtin command shows the type of file to which
3797each symbolic link points.
3798.TP 8
3799.B listmax \fR(+)
3800The maximum number of items which the \fIlist-choices\fR editor command
3801will list without asking first.
3802.TP 8
3803.B listmaxrows \fR(+)
3804The maximum number of rows of items which the \fIlist-choices\fR editor
3805command will list without asking first.
3806.TP 8
3807.B loginsh \fR(+)
3808Set by the shell if it is a login shell. Setting or unsetting it
3809within a shell has no effect. See also \fBshlvl\fR.
3810.TP 8
3811.B logout \fR(+)
3812Set by the shell to `normal' before a normal logout, `automatic' before
3813an automatic logout, and `hangup' if the shell was killed by a hangup
3814signal (see \fBSignal handling\fR). See also the \fBautologout\fR
3815shell variable.
3816.TP 8
3817.B mail
3818The names of the files or directories to check for incoming mail,
3819separated by whitespace, and optionally preceded by a numeric word.
3820Before each prompt, if 10 minutes have passed since the last check, the
3821shell checks each file and says `You have new mail.' (or, if \fBmail\fR
3822contains multiple files, `You have new mail in \fIname\fR.') if the
3823filesize is greater than zero in size and has a modification time
3824greater than its access time.
3825.PP
3826.RS +8
3827.PD
3828.PP
3829If you are in a login shell, then no mail file is reported unless it has
3830been modified after the time the shell has started up, to prevent
3831redundant notifications. Most login programs will tell you whether or not
3832you have mail when you log in.
3833.PP
3834If a file specified in \fBmail\fR is a directory, the shell will count each
3835file within that directory as a separate message, and will report `You have
3836\fIn\fR mails.' or `You have \fIn\fR mails in \fIname\fR.' as appropriate.
3837This functionality is provided primarily for those systems which store mail
3838in this manner, such as the Andrew Mail System.
3839.PP
3840If the first word of \fBmail\fR is numeric it is taken as a different mail
3841checking interval, in seconds.
3842.PP
3843Under very rare circumstances, the shell may report `You have mail.' instead
3844of `You have new mail.'
3845.RE
3846.TP 8
3847.B matchbeep \fR(+)
3848If set to `never', completion never beeps.
3849If set to `nomatch', it beeps only when there is no match.
3850If set to `ambiguous, it beeps when there are multiple matches.
3851If set to `notunique', it beeps when there is one exact and other longer matches.
3852If unset, `ambiguous' is used.
3853.TP 8
3854.B nobeep \fR(+)
3855If set, beeping is completely disabled.
3856See also \fBvisiblebell\fR.
3857.TP 8
3858.B noclobber
3859If set, restrictions are placed on output redirection to insure that files
3860are not accidentally destroyed and that `>>' redirections refer to existing
3861files, as described in the \fBInput/output\fR section.
3862.TP 8
3863.B noding
3864If set, disable the printing of `DING!' in the \fBprompt\fR time
3865specifiers at the change of hour.
3866.TP 8
3867.B noglob
3868If set, \fBFilename substitution\fR and \fBDirectory stack substitution\fR
3869(q.v.) are inhibited. This is most useful in shell scripts which do not deal
3870with filenames, or after a list of filenames has been obtained and further
3871expansions are not desirable.
3872.TP 8
3873.B nokanji \fR(+)
3874If set and the shell supports Kanji (see the \fBversion\fR shell variable),
3875it is disabled so that the meta key can be used.
3876.TP 8
3877.B nonomatch
3878If set, a \fBFilename substitution\fR or \fBDirectory stack substitution\fR
3879(q.v.) which does not match any
3880existing files is left untouched rather than causing an error.
3881It is still an error for the substitution to be
3882malformed, e.g., `echo [' still gives an error.
3883.TP 8
3884.B nostat \fR(+)
3885A list of directories (or glob-patterns which match directories; see
3886\fBFilename substitution\fR) that should not be \fIstat\fR(2)ed during a
3887completion operation. This is usually used to exclude directories which
3888take too much time to \fIstat\fR(2), for example \fI/afs\fR.
3889.TP 8
3890.B notify
3891If set, the shell announces job completions asynchronously.
3892The default is to present job completions just before printing a prompt.
3893.TP 8
3894.B oid \fR(+)
3895The user's real organization ID. (Domain/OS only)
3896.TP 8
3897.B owd \fR(+)
3898The old working directory, equivalent to the `\-' used by \fIcd\fR and \fIpushd\fR.
3899See also the \fBcwd\fR and \fBdirstack\fR shell variables.
3900.TP 8
3901.B path
3902A list of directories in which to look for executable commands.
3903A null word specifies the current directory.
3904If there is no \fBpath\fR variable then only full path names will execute.
3905\fBpath\fR is set by the shell at startup from the \fBPATH\fR environment
3906variable or, if \fBPATH\fR does not exist, to a system-dependent default
3907something like `(/usr/local/bin /usr/bsd /bin /usr/bin .)'.
3908The shell may put `.' first or last in \fBpath\fR or omit it entirely
3909depending on how it was compiled; see the \fBversion\fR shell variable.
3910A shell which is given neither the \fB\-c\fR nor the \fB\-t\fR option
3911hashes the contents of the directories in \fBpath\fR after
3912reading \fI~/.tcshrc\fR and each time \fBpath\fR is reset.
3913If one adds a new command to a directory in \fBpath\fR while the shell
3914is active, one may need to do a \fIrehash\fR for the shell to find it.
3915.TP 8
3916.B printexitvalue \fR(+)
3917If set and an interactive program exits with a non-zero status, the shell
3918prints `Exit \fBstatus\fR'.
3919.TP 8
3920.B prompt
3921The string which is printed before reading each command from the terminal.
3922\fBprompt\fR may include any of the following formatting sequences (+), which
3923are replaced by the given information:
3924.PP
3925.RS +8
3926.PD 0
3927.TP 4
3928%/
3929The current working directory.
3930.TP 4
3931%~
3932The current working directory, but with one's home directory
3933represented by `~' and other users' home directories represented by
3934`~user' as per \fBFilename substitution\fR. `~user' substitution
3935happens only if the shell has already used `~\fIuser\fR' in a pathname
3936in the current session.
3937.TP 4
3938%c[[0]\fIn\fR], %.[[0]\fIn\fR]
3939The trailing component of the current working directory, or \fIn\fR
3940trailing components if a digit \fIn\fR is given.
3941If \fIn\fR begins with `0', the number of skipped components precede
3942the trailing component(s) in the format `/<\fIskipped\fR>trailing'.
3943If the \fBellipsis\fR shell variable is set, skipped components
3944are represented by an ellipsis so the whole becomes `...trailing'.
3945`~' substitution is done as in `%~' above, but the `~' component
3946is ignored when counting trailing components.
3947.TP 4
3948%C
3949Like %c, but without `~' substitution.
3950.TP 4
3951%h, %!, !
3952The current history event number.
3953.TP 4
3954%M
3955The full hostname.
3956.TP 4
3957%m
3958The hostname up to the first `.'.
3959.TP 4
3960%S (%s)
3961Start (stop) standout mode.
3962.TP 4
3963%B (%b)
3964Start (stop) boldfacing mode.
3965.TP 4
3966%U (%u)
3967Start (stop) underline mode.
3968.TP 4
3969%t, %@
3970The time of day in 12-hour AM/PM format.
3971.TP 4
3972%T
3973Like `%t', but in 24-hour format (but see the \fBampm\fR shell variable).
3974.TP 4
3975%p
3976The `precise' time of day in 12-hour AM/PM format, with seconds.
3977.TP 4
3978%P
3979Like `%p', but in 24-hour format (but see the \fBampm\fR shell variable).
3980.TP 4
3981\e\fIc\fR
3982\fIc\fR is parsed as in \fIbindkey\fR.
3983.TP 4
3984^\fIc\fR
3985\fIc\fR is parsed as in \fIbindkey\fR.
3986.TP 4
3987%%
3988A single `%'.
3989.TP 4
3990%n
3991The user name.
3992.TP 4
3993%d
3994The weekday in `Day' format.
3995.TP 4
3996%D
3997The day in `dd' format.
3998.TP 4
3999%w
4000The month in `Mon' format.
4001.TP 4
4002%W
4003The month in `mm' format.
4004.TP 4
4005%y
4006The year in `yy' format.
4007.TP 4
4008%Y
4009The year in `yyyy' format.
4010.TP 4
4011%l
4012The shell's tty.
4013.TP 4
4014%L
4015Clears from the end of the prompt to end of the display or the end of the line.
4016.TP 4
4017%$
4018Expands the shell or environment variable name immediately after the `$'.
4019.TP 4
4020%#
4021`>' (or the first character of the \fBpromptchars\fR shell variable)
4022for normal users, `#' (or the second character of \fBpromptchars\fR)
4023for the superuser.
4024.TP 4
4025%{\fIstring\fR%}
4026Includes \fIstring\fR as a literal escape sequence.
4027It should be used only to change terminal attributes and
4028should not move the cursor location. This
4029cannot be the last sequence in \fBprompt\fR.
4030.TP 4
4031%?
4032The return code of the command executed just before the prompt.
4033.TP 4
4034%R
4035In \fBprompt2\fR, the status of the parser.
4036In \fBprompt3\fR, the corrected string.
4037In \fBhistory\fR, the history string.
4038.PD
4039.PP
4040`%B', `%S', `%U' and `%{\fIstring\fR%}' are available in only
4041eight-bit-clean shells; see the \fBversion\fR shell variable.
4042.PP
4043The bold, standout and underline sequences are often used to distinguish a
4044superuser shell. For example,
4045.IP "" 4
4046> set prompt = "%m [%h] %B[%@]%b [%/] you rang? "
4047.br
4048tut [37] \fB[2:54pm]\fR [/usr/accts/sys] you rang? _
4049.PP
4050If `%t', `%@', `%T', `%p', or `%P' is used, and \fBnoding\fR is not set,
4051then print `DING!' on the change of hour (i.e, `:00' minutes) instead of
4052the actual time.
4053.PP
4054Set by default to `%# ' in interactive shells.
4055.RE
4056.TP 8
4057.B prompt2 \fR(+)
4058The string with which to prompt in \fIwhile\fR and \fIforeach\fR loops and
4059after lines ending in `\\'.
4060The same format sequences may be used as in \fBprompt\fR (q.v.);
4061note the variable meaning of `%R'.
4062Set by default to `%R? ' in interactive shells.
4063.TP 8
4064.B prompt3 \fR(+)
4065The string with which to prompt when confirming automatic spelling correction.
4066The same format sequences may be used as in \fBprompt\fR (q.v.);
4067note the variable meaning of `%R'.
4068Set by default to `CORRECT>%R (y|n|e|a)? ' in interactive shells.
4069.TP 8
4070.B promptchars \fR(+)
4071If set (to a two-character string), the `%#' formatting sequence in the
4072\fBprompt\fR shell variable is replaced with the first character for
4073normal users and the second character for the superuser.
4074.TP 8
4075.B pushdtohome \fR(+)
4076If set, \fIpushd\fR without arguments does `pushd ~', like \fIcd\fR.
4077.TP 8
4078.B pushdsilent \fR(+)
4079If set, \fIpushd\fR and \fIpopd\fR do not print the directory stack.
4080.TP 8
4081.B recexact \fR(+)
4082If set, completion completes on an exact match even if a longer match is
4083possible.
4084.TP 8
4085.B recognize_only_executables \fR(+)
4086If set, command listing displays only files in the path that are
4087executable. Slow.
4088.TP 8
4089.B rmstar \fR(+)
4090If set, the user is prompted before `rm *' is executed.
4091.TP 8
4092.B rprompt \fR(+)
4093The string to print on the right-hand side of the screen (after
4094the command input) when the prompt is being displayed on the left.
4095It recognizes the same formatting characters as \fBprompt\fR.
4096It will automatically disappear and reappear as necessary, to ensure that
4097command input isn't obscured, and will appear only if the prompt,
4098command input, and itself will fit together on the first line.
4099If \fBedit\fR isn't set, then \fBrprompt\fR will be printed after
4100the prompt and before the command input.
4101.TP 8
4102.B savedirs \fR(+)
4103If set, the shell does `dirs \-S' before exiting.
4104If the first word is set to a number, at most that many directory stack
4105entries are saved.
4106.TP 8
4107.B savehist
4108If set, the shell does `history \-S' before exiting.
4109If the first word is set to a number, at most that many lines are saved.
4110(The number must be less than or equal to \fBhistory\fR.)
4111If the second word is set to `merge', the history list is merged with
4112the existing history file instead of replacing it (if there is one) and
4113sorted by time stamp and the most recent events are retained. (+)
4114.TP 8
4115.B sched \fR(+)
4116The format in which the \fIsched\fR builtin command prints scheduled events;
4117if not given, `%h\\t%T\\t%R\\n' is used.
4118The format sequences are described above under \fBprompt\fR;
4119note the variable meaning of `%R'.
4120.TP 8
4121.B shell
4122The file in which the shell resides. This is used in forking
4123shells to interpret files which have execute bits set, but
4124which are not executable by the system. (See the description
4125of \fBBuiltin and non-builtin command execution\fR.) Initialized to the
4126(system-dependent) home of the shell.
4127.TP 8
4128.B shlvl \fR(+)
4129The number of nested shells.
4130Reset to 1 in login shells.
4131See also \fBloginsh\fR.
4132.TP 8
4133.B status
4134The status returned by the last command. If it terminated
4135abnormally, then 0200 is added to the status. Builtin commands
4136which fail return exit status `1', all other builtin commands
4137return status `0'.
4138.TP 8
4139.B symlinks \fR(+)
4140Can be set to several different values to control symbolic link (`symlink')
4141resolution:
4142.RS +8
4143.PP
4144If set to `chase', whenever the current directory changes to a directory
4145containing a symbolic link, it is expanded to the real name of the directory
4146to which the link points. This does not work for the user's home directory;
4147this is a bug.
4148.PP
4149If set to `ignore', the shell tries to construct a current directory
4150relative to the current directory before the link was crossed.
4151This means that \fIcd\fRing through a symbolic link and then `cd ..'ing
4152returns one to the original directory. This affects only builtin commands
4153and filename completion.
4154.PP
4155If set to `expand', the shell tries to fix symbolic links by actually expanding
4156arguments which look like path names. This affects any command, not just
4157builtins. Unfortunately, this does not work for hard-to-recognize filenames,
4158such as those embedded in command options. Expansion may be prevented by
4159quoting. While this setting is usually the most convenient, it is sometimes
4160misleading and sometimes confusing when it fails to recognize an argument
4161which should be expanded. A compromise is to use `ignore' and use the
4162editor command \fInormalize-path\fR (bound by default to ^X-n) when necessary.
4163.PP
4164Some examples are in order. First, let's set up some play directories:
4165.IP "" 4
4166> cd /tmp
4167.br
4168> mkdir from from/src to
4169.br
| 3815.B listflags \fR(+)
3816If set to `x', `a' or `A', or any combination thereof (e.g., `xA'), they
3817are used as flags to \fIls\-F\fR, making it act like `ls \-xF', `ls
3818\-Fa', `ls \-FA' or a combination (e.g., `ls \-FxA'): `a' shows all
3819files (even if they start with a `.'), `A' shows all files but `.' and
3820`..', and `x' sorts across instead of down. If the second word of
3821\fBlistflags\fR is set, it is used as the path to `ls(1)'.
3822.TP 8
3823.B listjobs \fR(+)
3824If set, all jobs are listed when a job is suspended. If set to `long',
3825the listing is in long format.
3826.TP 8
3827.B listlinks \fR(+)
3828If set, the \fIls\-F\fR builtin command shows the type of file to which
3829each symbolic link points.
3830.TP 8
3831.B listmax \fR(+)
3832The maximum number of items which the \fIlist-choices\fR editor command
3833will list without asking first.
3834.TP 8
3835.B listmaxrows \fR(+)
3836The maximum number of rows of items which the \fIlist-choices\fR editor
3837command will list without asking first.
3838.TP 8
3839.B loginsh \fR(+)
3840Set by the shell if it is a login shell. Setting or unsetting it
3841within a shell has no effect. See also \fBshlvl\fR.
3842.TP 8
3843.B logout \fR(+)
3844Set by the shell to `normal' before a normal logout, `automatic' before
3845an automatic logout, and `hangup' if the shell was killed by a hangup
3846signal (see \fBSignal handling\fR). See also the \fBautologout\fR
3847shell variable.
3848.TP 8
3849.B mail
3850The names of the files or directories to check for incoming mail,
3851separated by whitespace, and optionally preceded by a numeric word.
3852Before each prompt, if 10 minutes have passed since the last check, the
3853shell checks each file and says `You have new mail.' (or, if \fBmail\fR
3854contains multiple files, `You have new mail in \fIname\fR.') if the
3855filesize is greater than zero in size and has a modification time
3856greater than its access time.
3857.PP
3858.RS +8
3859.PD
3860.PP
3861If you are in a login shell, then no mail file is reported unless it has
3862been modified after the time the shell has started up, to prevent
3863redundant notifications. Most login programs will tell you whether or not
3864you have mail when you log in.
3865.PP
3866If a file specified in \fBmail\fR is a directory, the shell will count each
3867file within that directory as a separate message, and will report `You have
3868\fIn\fR mails.' or `You have \fIn\fR mails in \fIname\fR.' as appropriate.
3869This functionality is provided primarily for those systems which store mail
3870in this manner, such as the Andrew Mail System.
3871.PP
3872If the first word of \fBmail\fR is numeric it is taken as a different mail
3873checking interval, in seconds.
3874.PP
3875Under very rare circumstances, the shell may report `You have mail.' instead
3876of `You have new mail.'
3877.RE
3878.TP 8
3879.B matchbeep \fR(+)
3880If set to `never', completion never beeps.
3881If set to `nomatch', it beeps only when there is no match.
3882If set to `ambiguous, it beeps when there are multiple matches.
3883If set to `notunique', it beeps when there is one exact and other longer matches.
3884If unset, `ambiguous' is used.
3885.TP 8
3886.B nobeep \fR(+)
3887If set, beeping is completely disabled.
3888See also \fBvisiblebell\fR.
3889.TP 8
3890.B noclobber
3891If set, restrictions are placed on output redirection to insure that files
3892are not accidentally destroyed and that `>>' redirections refer to existing
3893files, as described in the \fBInput/output\fR section.
3894.TP 8
3895.B noding
3896If set, disable the printing of `DING!' in the \fBprompt\fR time
3897specifiers at the change of hour.
3898.TP 8
3899.B noglob
3900If set, \fBFilename substitution\fR and \fBDirectory stack substitution\fR
3901(q.v.) are inhibited. This is most useful in shell scripts which do not deal
3902with filenames, or after a list of filenames has been obtained and further
3903expansions are not desirable.
3904.TP 8
3905.B nokanji \fR(+)
3906If set and the shell supports Kanji (see the \fBversion\fR shell variable),
3907it is disabled so that the meta key can be used.
3908.TP 8
3909.B nonomatch
3910If set, a \fBFilename substitution\fR or \fBDirectory stack substitution\fR
3911(q.v.) which does not match any
3912existing files is left untouched rather than causing an error.
3913It is still an error for the substitution to be
3914malformed, e.g., `echo [' still gives an error.
3915.TP 8
3916.B nostat \fR(+)
3917A list of directories (or glob-patterns which match directories; see
3918\fBFilename substitution\fR) that should not be \fIstat\fR(2)ed during a
3919completion operation. This is usually used to exclude directories which
3920take too much time to \fIstat\fR(2), for example \fI/afs\fR.
3921.TP 8
3922.B notify
3923If set, the shell announces job completions asynchronously.
3924The default is to present job completions just before printing a prompt.
3925.TP 8
3926.B oid \fR(+)
3927The user's real organization ID. (Domain/OS only)
3928.TP 8
3929.B owd \fR(+)
3930The old working directory, equivalent to the `\-' used by \fIcd\fR and \fIpushd\fR.
3931See also the \fBcwd\fR and \fBdirstack\fR shell variables.
3932.TP 8
3933.B path
3934A list of directories in which to look for executable commands.
3935A null word specifies the current directory.
3936If there is no \fBpath\fR variable then only full path names will execute.
3937\fBpath\fR is set by the shell at startup from the \fBPATH\fR environment
3938variable or, if \fBPATH\fR does not exist, to a system-dependent default
3939something like `(/usr/local/bin /usr/bsd /bin /usr/bin .)'.
3940The shell may put `.' first or last in \fBpath\fR or omit it entirely
3941depending on how it was compiled; see the \fBversion\fR shell variable.
3942A shell which is given neither the \fB\-c\fR nor the \fB\-t\fR option
3943hashes the contents of the directories in \fBpath\fR after
3944reading \fI~/.tcshrc\fR and each time \fBpath\fR is reset.
3945If one adds a new command to a directory in \fBpath\fR while the shell
3946is active, one may need to do a \fIrehash\fR for the shell to find it.
3947.TP 8
3948.B printexitvalue \fR(+)
3949If set and an interactive program exits with a non-zero status, the shell
3950prints `Exit \fBstatus\fR'.
3951.TP 8
3952.B prompt
3953The string which is printed before reading each command from the terminal.
3954\fBprompt\fR may include any of the following formatting sequences (+), which
3955are replaced by the given information:
3956.PP
3957.RS +8
3958.PD 0
3959.TP 4
3960%/
3961The current working directory.
3962.TP 4
3963%~
3964The current working directory, but with one's home directory
3965represented by `~' and other users' home directories represented by
3966`~user' as per \fBFilename substitution\fR. `~user' substitution
3967happens only if the shell has already used `~\fIuser\fR' in a pathname
3968in the current session.
3969.TP 4
3970%c[[0]\fIn\fR], %.[[0]\fIn\fR]
3971The trailing component of the current working directory, or \fIn\fR
3972trailing components if a digit \fIn\fR is given.
3973If \fIn\fR begins with `0', the number of skipped components precede
3974the trailing component(s) in the format `/<\fIskipped\fR>trailing'.
3975If the \fBellipsis\fR shell variable is set, skipped components
3976are represented by an ellipsis so the whole becomes `...trailing'.
3977`~' substitution is done as in `%~' above, but the `~' component
3978is ignored when counting trailing components.
3979.TP 4
3980%C
3981Like %c, but without `~' substitution.
3982.TP 4
3983%h, %!, !
3984The current history event number.
3985.TP 4
3986%M
3987The full hostname.
3988.TP 4
3989%m
3990The hostname up to the first `.'.
3991.TP 4
3992%S (%s)
3993Start (stop) standout mode.
3994.TP 4
3995%B (%b)
3996Start (stop) boldfacing mode.
3997.TP 4
3998%U (%u)
3999Start (stop) underline mode.
4000.TP 4
4001%t, %@
4002The time of day in 12-hour AM/PM format.
4003.TP 4
4004%T
4005Like `%t', but in 24-hour format (but see the \fBampm\fR shell variable).
4006.TP 4
4007%p
4008The `precise' time of day in 12-hour AM/PM format, with seconds.
4009.TP 4
4010%P
4011Like `%p', but in 24-hour format (but see the \fBampm\fR shell variable).
4012.TP 4
4013\e\fIc\fR
4014\fIc\fR is parsed as in \fIbindkey\fR.
4015.TP 4
4016^\fIc\fR
4017\fIc\fR is parsed as in \fIbindkey\fR.
4018.TP 4
4019%%
4020A single `%'.
4021.TP 4
4022%n
4023The user name.
4024.TP 4
4025%d
4026The weekday in `Day' format.
4027.TP 4
4028%D
4029The day in `dd' format.
4030.TP 4
4031%w
4032The month in `Mon' format.
4033.TP 4
4034%W
4035The month in `mm' format.
4036.TP 4
4037%y
4038The year in `yy' format.
4039.TP 4
4040%Y
4041The year in `yyyy' format.
4042.TP 4
4043%l
4044The shell's tty.
4045.TP 4
4046%L
4047Clears from the end of the prompt to end of the display or the end of the line.
4048.TP 4
4049%$
4050Expands the shell or environment variable name immediately after the `$'.
4051.TP 4
4052%#
4053`>' (or the first character of the \fBpromptchars\fR shell variable)
4054for normal users, `#' (or the second character of \fBpromptchars\fR)
4055for the superuser.
4056.TP 4
4057%{\fIstring\fR%}
4058Includes \fIstring\fR as a literal escape sequence.
4059It should be used only to change terminal attributes and
4060should not move the cursor location. This
4061cannot be the last sequence in \fBprompt\fR.
4062.TP 4
4063%?
4064The return code of the command executed just before the prompt.
4065.TP 4
4066%R
4067In \fBprompt2\fR, the status of the parser.
4068In \fBprompt3\fR, the corrected string.
4069In \fBhistory\fR, the history string.
4070.PD
4071.PP
4072`%B', `%S', `%U' and `%{\fIstring\fR%}' are available in only
4073eight-bit-clean shells; see the \fBversion\fR shell variable.
4074.PP
4075The bold, standout and underline sequences are often used to distinguish a
4076superuser shell. For example,
4077.IP "" 4
4078> set prompt = "%m [%h] %B[%@]%b [%/] you rang? "
4079.br
4080tut [37] \fB[2:54pm]\fR [/usr/accts/sys] you rang? _
4081.PP
4082If `%t', `%@', `%T', `%p', or `%P' is used, and \fBnoding\fR is not set,
4083then print `DING!' on the change of hour (i.e, `:00' minutes) instead of
4084the actual time.
4085.PP
4086Set by default to `%# ' in interactive shells.
4087.RE
4088.TP 8
4089.B prompt2 \fR(+)
4090The string with which to prompt in \fIwhile\fR and \fIforeach\fR loops and
4091after lines ending in `\\'.
4092The same format sequences may be used as in \fBprompt\fR (q.v.);
4093note the variable meaning of `%R'.
4094Set by default to `%R? ' in interactive shells.
4095.TP 8
4096.B prompt3 \fR(+)
4097The string with which to prompt when confirming automatic spelling correction.
4098The same format sequences may be used as in \fBprompt\fR (q.v.);
4099note the variable meaning of `%R'.
4100Set by default to `CORRECT>%R (y|n|e|a)? ' in interactive shells.
4101.TP 8
4102.B promptchars \fR(+)
4103If set (to a two-character string), the `%#' formatting sequence in the
4104\fBprompt\fR shell variable is replaced with the first character for
4105normal users and the second character for the superuser.
4106.TP 8
4107.B pushdtohome \fR(+)
4108If set, \fIpushd\fR without arguments does `pushd ~', like \fIcd\fR.
4109.TP 8
4110.B pushdsilent \fR(+)
4111If set, \fIpushd\fR and \fIpopd\fR do not print the directory stack.
4112.TP 8
4113.B recexact \fR(+)
4114If set, completion completes on an exact match even if a longer match is
4115possible.
4116.TP 8
4117.B recognize_only_executables \fR(+)
4118If set, command listing displays only files in the path that are
4119executable. Slow.
4120.TP 8
4121.B rmstar \fR(+)
4122If set, the user is prompted before `rm *' is executed.
4123.TP 8
4124.B rprompt \fR(+)
4125The string to print on the right-hand side of the screen (after
4126the command input) when the prompt is being displayed on the left.
4127It recognizes the same formatting characters as \fBprompt\fR.
4128It will automatically disappear and reappear as necessary, to ensure that
4129command input isn't obscured, and will appear only if the prompt,
4130command input, and itself will fit together on the first line.
4131If \fBedit\fR isn't set, then \fBrprompt\fR will be printed after
4132the prompt and before the command input.
4133.TP 8
4134.B savedirs \fR(+)
4135If set, the shell does `dirs \-S' before exiting.
4136If the first word is set to a number, at most that many directory stack
4137entries are saved.
4138.TP 8
4139.B savehist
4140If set, the shell does `history \-S' before exiting.
4141If the first word is set to a number, at most that many lines are saved.
4142(The number must be less than or equal to \fBhistory\fR.)
4143If the second word is set to `merge', the history list is merged with
4144the existing history file instead of replacing it (if there is one) and
4145sorted by time stamp and the most recent events are retained. (+)
4146.TP 8
4147.B sched \fR(+)
4148The format in which the \fIsched\fR builtin command prints scheduled events;
4149if not given, `%h\\t%T\\t%R\\n' is used.
4150The format sequences are described above under \fBprompt\fR;
4151note the variable meaning of `%R'.
4152.TP 8
4153.B shell
4154The file in which the shell resides. This is used in forking
4155shells to interpret files which have execute bits set, but
4156which are not executable by the system. (See the description
4157of \fBBuiltin and non-builtin command execution\fR.) Initialized to the
4158(system-dependent) home of the shell.
4159.TP 8
4160.B shlvl \fR(+)
4161The number of nested shells.
4162Reset to 1 in login shells.
4163See also \fBloginsh\fR.
4164.TP 8
4165.B status
4166The status returned by the last command. If it terminated
4167abnormally, then 0200 is added to the status. Builtin commands
4168which fail return exit status `1', all other builtin commands
4169return status `0'.
4170.TP 8
4171.B symlinks \fR(+)
4172Can be set to several different values to control symbolic link (`symlink')
4173resolution:
4174.RS +8
4175.PP
4176If set to `chase', whenever the current directory changes to a directory
4177containing a symbolic link, it is expanded to the real name of the directory
4178to which the link points. This does not work for the user's home directory;
4179this is a bug.
4180.PP
4181If set to `ignore', the shell tries to construct a current directory
4182relative to the current directory before the link was crossed.
4183This means that \fIcd\fRing through a symbolic link and then `cd ..'ing
4184returns one to the original directory. This affects only builtin commands
4185and filename completion.
4186.PP
4187If set to `expand', the shell tries to fix symbolic links by actually expanding
4188arguments which look like path names. This affects any command, not just
4189builtins. Unfortunately, this does not work for hard-to-recognize filenames,
4190such as those embedded in command options. Expansion may be prevented by
4191quoting. While this setting is usually the most convenient, it is sometimes
4192misleading and sometimes confusing when it fails to recognize an argument
4193which should be expanded. A compromise is to use `ignore' and use the
4194editor command \fInormalize-path\fR (bound by default to ^X-n) when necessary.
4195.PP
4196Some examples are in order. First, let's set up some play directories:
4197.IP "" 4
4198> cd /tmp
4199.br
4200> mkdir from from/src to
4201.br
|
4170> ln \-s from/src to/dist
| 4202> ln \-s from/src to/dst
|
4171.PP
4172Here's the behavior with \fBsymlinks\fR unset,
4173.IP "" 4
| 4203.PP
4204Here's the behavior with \fBsymlinks\fR unset,
4205.IP "" 4
|
4174> cd /tmp/to/dist; echo $cwd
| 4206> cd /tmp/to/dst; echo $cwd
|
4175.br
| 4207.br
|
4176/tmp/to/dist
| 4208/tmp/to/dst
|
4177.br
4178> cd ..; echo $cwd
4179.br
4180/tmp/from
4181.PP
4182here's the behavior with \fBsymlinks\fR set to `chase',
4183.IP "" 4
4184> cd /tmp/to/dst; echo $cwd
4185.br
4186/tmp/from/src
4187.br
4188> cd ..; echo $cwd
4189.br
4190/tmp/from
4191.PP
4192here's the behavior with \fBsymlinks\fR set to `ignore',
4193.IP "" 4
| 4209.br
4210> cd ..; echo $cwd
4211.br
4212/tmp/from
4213.PP
4214here's the behavior with \fBsymlinks\fR set to `chase',
4215.IP "" 4
4216> cd /tmp/to/dst; echo $cwd
4217.br
4218/tmp/from/src
4219.br
4220> cd ..; echo $cwd
4221.br
4222/tmp/from
4223.PP
4224here's the behavior with \fBsymlinks\fR set to `ignore',
4225.IP "" 4
|
4194> cd /tmp/to/dist; echo $cwd
| 4226> cd /tmp/to/dst; echo $cwd
|
4195.br
4196/tmp/to/dst
4197.br
4198> cd ..; echo $cwd
4199.br
4200/tmp/to
4201.PP
4202and here's the behavior with \fBsymlinks\fR set to `expand'.
4203.IP "" 4
| 4227.br
4228/tmp/to/dst
4229.br
4230> cd ..; echo $cwd
4231.br
4232/tmp/to
4233.PP
4234and here's the behavior with \fBsymlinks\fR set to `expand'.
4235.IP "" 4
|
4204> cd /tmp/to/dist; echo $cwd
| 4236> cd /tmp/to/dst; echo $cwd
|
4205.br
4206/tmp/to/dst
4207.br
4208> cd ..; echo $cwd
4209.br
4210/tmp/to
4211.br
| 4237.br
4238/tmp/to/dst
4239.br
4240> cd ..; echo $cwd
4241.br
4242/tmp/to
4243.br
|
4212> cd /tmp/to/dist; echo $cwd
| 4244> cd /tmp/to/dst; echo $cwd
|
4213.br
4214/tmp/to/dst
4215.br
4216> cd ".."; echo $cwd
4217.br
4218/tmp/from
4219.br
4220> /bin/echo ..
4221.br
4222/tmp/to
4223.br
4224> /bin/echo ".."
4225.br
4226\&..
4227.PP
4228Note that `expand' expansion 1) works just like `ignore' for builtins
4229like \fIcd\fR, 2) is prevented by quoting, and 3) happens before
4230filenames are passed to non-builtin commands.
4231.RE
4232.TP 8
4233.B tcsh \fR(+)
4234The version number of the shell in the format `R.VV.PP',
4235where `R' is the major release number, `VV' the current version
4236and `PP' the patchlevel.
4237.TP 8
4238.B term
4239The terminal type. Usually set in \fI~/.login\fR as described under
4240\fBStartup and shutdown\fR.
4241.TP 8
4242.B time
4243If set to a number, then the \fItime\fR builtin (q.v.) executes automatically
4244after each command which takes more than that many CPU seconds.
4245If there is a second word, it is used as a format string for the output
4246of the \fItime\fR builtin. (u) The following sequences may be used in the
4247format string:
4248.PP
4249.RS +8
4250.PD 0
4251.TP 4
4252%U
4253The time the process spent in user mode in cpu seconds.
4254.TP 4
4255%S
4256The time the process spent in kernel mode in cpu seconds.
4257.TP 4
4258%E
4259The elapsed (wall clock) time in seconds.
4260.TP 4
4261%P
4262The CPU percentage computed as (%U + %S) / %E.
4263.TP 4
4264%W
4265Number of times the process was swapped.
4266.TP 4
4267%X
4268The average amount in (shared) text space used in Kbytes.
4269.TP 4
4270%D
4271The average amount in (unshared) data/stack space used in Kbytes.
4272.TP 4
4273%K
4274The total space used (%X + %D) in Kbytes.
4275.TP 4
4276%M
4277The maximum memory the process had in use at any time in Kbytes.
4278.TP 4
4279%F
4280The number of major page faults (page needed to be brought from disk).
4281.TP 4
4282%R
4283The number of minor page faults.
4284.TP 4
4285%I
4286The number of input operations.
4287.TP 4
4288%O
4289The number of output operations.
4290.TP 4
4291%r
4292The number of socket messages received.
4293.TP 4
4294%s
4295The number of socket messages sent.
4296.TP 4
4297%k
4298The number of signals received.
4299.TP 4
4300%w
4301The number of voluntary context switches (waits).
4302.TP 4
4303%c
4304The number of involuntary context switches.
4305.PD
4306.PP
4307Only the first four sequences are supported on systems without BSD resource
4308limit functions.
4309The default time format is `%Uu %Ss %E %P %X+%Dk %I+%Oio %Fpf+%Ww' for
4310systems that support resource usage reporting and `%Uu %Ss %E %P' for
4311systems that do not.
4312.PP
4313Under Sequent's DYNIX/ptx, %X, %D, %K, %r and %s are not
4314available, but the following additional sequences are:
4315.PP
4316.PD 0
4317.TP 4
4318%Y
4319The number of system calls performed.
4320.TP 4
4321%Z
4322The number of pages which are zero-filled on demand.
4323.TP 4
4324%i
4325The number of times a process's resident set size was increased by the kernel.
4326.TP 4
4327%d
4328The number of times a process's resident set size was decreased by the kernel.
4329.TP 4
4330%l
4331The number of read system calls performed.
4332.TP 4
4333%m
4334The number of write system calls performed.
4335.TP 4
4336%p
4337The number of reads from raw disk devices.
4338.TP 4
4339%q
4340The number of writes to raw disk devices.
4341.PD
4342.PP
4343and the default time format is `%Uu %Ss $E %P %I+%Oio %Fpf+%Ww'.
4344Note that the CPU percentage can be higher than 100% on multi-processors.
4345.RE
4346.TP 8
4347.B tperiod \fR(+)
4348The period, in minutes, between executions of the \fIperiodic\fR special alias.
4349.TP 8
4350.B tty \fR(+)
4351The name of the tty, or empty if not attached to one.
4352.TP 8
4353.B uid \fR(+)
4354The user's real user ID.
4355.TP 8
4356.B user
4357The user's login name.
4358.TP 8
4359.B verbose
4360If set, causes the words of each
4361command to be printed, after history substitution (if any).
4362Set by the \fB\-v\fR command line option.
4363.TP 8
4364.B version \fR(+)
4365The version ID stamp. It contains the shell's version number (see \fBtcsh\fR),
4366origin, release date, vendor, operating system and machine (see \fBVENDOR\fR,
4367\fBOSTYPE\fR and \fBMACHTYPE\fR) and a comma-separated
4368list of options which were set at compile time.
4369Options which are set by default in the distribution are noted.
4370.PP
4371.RS +8
4372.PD 0
4373.TP 4
43748b
4375The shell is eight bit clean; default
4376.TP 4
43777b
4378The shell is not eight bit clean
4379.TP 4
4380nls
4381The system's NLS is used; default for systems with NLS
4382.TP 4
4383lf
4384Login shells execute \fI/etc/csh.login\fR before instead of after
4385\fI/etc/csh.cshrc\fR and \fI~/.login\fR before instead of after
4386\fI~/.tcshrc\fR and \fI~/.history\fR.
4387.TP 4
4388dl
4389`.' is put last in \fBpath\fR for security; default
4390.TP 4
4391nd
4392`.' is omitted from \fBpath\fR for security
4393.TP 4
4394vi
4395\fIvi\fR-style editing is the default rather than \fIemacs\fR
4396.TP 4
4397dtr
4398Login shells drop DTR when exiting
4399.TP 4
4400bye
4401\fIbye\fR is a synonym for \fIlogout\fR and \fIlog\fR
4402is an alternate name for \fIwatchlog\fR
4403.TP 4
4404al
4405\fBautologout\fR is enabled; default
4406.TP 4
4407kan
4408Kanji is used if appropriate according to locale settings,
4409unless the \fBnokanji\fR shell variable is set
4410.TP 4
4411sm
4412The system's \fImalloc\fR(3) is used
4413.TP 4
4414hb
4415The `#!<program> <args>' convention is emulated when executing shell scripts
4416.TP 4
4417ng
4418The \fInewgrp\fR builtin is available
4419.TP 4
4420rh
4421The shell attempts to set the \fBREMOTEHOST\fR environment variable
4422.TP 4
4423afs
4424The shell verifies your password with the kerberos server if local
4425authentication fails. The \fBafsuser\fR shell variable or the
4426\fBAFSUSER\fR environment variable override your local username if set.
4427.PD
4428.PP
4429An administrator may enter additional strings to indicate differences
4430in the local version.
4431.RE
4432.TP 8
4433.B visiblebell \fR(+)
4434If set, a screen flash is used rather than the audible bell.
4435See also \fBnobeep\fR.
4436.TP 8
4437.B watch \fR(+)
4438A list of user/terminal pairs to watch for logins and logouts.
4439If either the user is `any' all terminals are watched for the given user
4440and vice versa.
4441Setting \fBwatch\fR to `(any any)' watches all users and terminals.
4442For example,
4443.RS +8
4444.IP "" 4
4445set watch = (george ttyd1 any console $user any)
4446.PP
4447reports activity of the user `george' on ttyd1, any user on the console, and
4448oneself (or a trespasser) on any terminal.
4449.PP
4450Logins and logouts are checked every 10 minutes by default, but the first
4451word of \fBwatch\fR can be set to a number to check every so many minutes.
4452For example,
4453.IP "" 4
4454set watch = (1 any any)
4455.PP
4456reports any login/logout once every minute. For the impatient, the \fIlog\fR
4457builtin command triggers a \fBwatch\fR report at any time. All current logins
4458are reported (as with the \fIlog\fR builtin) when \fBwatch\fR is first set.
4459.PP
4460The \fBwho\fR shell variable controls the format of \fBwatch\fR reports.
4461.RE
4462.TP 8
4463.B who \fR(+)
4464The format string for \fBwatch\fR messages. The following sequences
4465are replaced by the given information:
4466.PP
4467.RS +8
4468.PD 0
4469.TP 4
4470%n
4471The name of the user who logged in/out.
4472.TP 4
4473%a
4474The observed action, i.e., `logged on', `logged off' or `replaced \fIolduser\fR on'.
4475.TP 4
4476%l
4477The terminal (tty) on which the user logged in/out.
4478.TP 4
4479%M
4480The full hostname of the remote host, or `local' if the login/logout was
4481from the local host.
4482.TP 4
4483%m
4484The hostname of the remote host up to the first `.'.
4485The full name is printed if it is an IP address or an X Window System display.
4486.PD
4487.PP
4488%M and %m are available on only systems that store the remote hostname in
4489\fI/etc/utmp\fR.
4490If unset, `%n has %a %l from %m.' is used, or `%n has %a %l.' on systems
4491which don't store the remote hostname.
4492.RE
4493.TP 8
4494.B wordchars \fR(+)
4495A list of non-alphanumeric characters to be considered part of a word by the
4496\fIforward-word\fR, \fIbackward-word\fR etc., editor commands.
4497If unset, `*?_\-.[]~=' is used.
4498.SH ENVIRONMENT
4499.TP 8
4500.B AFSUSER \fR(+)
4501Equivalent to the \fBafsuser\fR shell variable.
4502.TP 8
4503.B COLUMNS
4504The number of columns in the terminal. See \fBTerminal management\fR.
4505.TP 8
4506.B DISPLAY
4507Used by X Window System (see \fIX\fR(1)).
4508If set, the shell does not set \fBautologout\fR (q.v.).
4509.TP 8
4510.B EDITOR
4511The pathname to a default editor.
4512See also the \fBVISUAL\fR environment variable
4513and the \fIrun-fg-editor\fR editor command.
4514.TP 8
4515.B GROUP \fR(+)
4516Equivalent to the \fBgroup\fR shell variable.
4517.TP 8
4518.B HOME
4519Equivalent to the \fBhome\fR shell variable.
4520.TP 8
4521.B HOST \fR(+)
4522Initialized to the name of the machine on which the shell
4523is running, as determined by the \fIgethostname\fR(2) system call.
4524.TP 8
4525.B HOSTTYPE \fR(+)
4526Initialized to the type of machine on which the shell
4527is running, as determined at compile time. This variable is obsolete and
4528will be removed in a future version.
4529.TP 8
4530.B HPATH \fR(+)
4531A colon-separated list of directories in which the \fIrun-help\fR editor
4532command looks for command documentation.
4533.TP 8
4534.B LANG
4535Gives the preferred character environment.
4536See \fBNative Language System support\fR.
4537.TP 8
4538.B LC_CTYPE
4539If set, only ctype character handling is changed.
4540See \fBNative Language System support\fR.
4541.TP 8
4542.B LINES
4543The number of lines in the terminal. See \fBTerminal management\fR.
4544.TP 8
4545.B LS_COLORS
4546The format of this variable is reminiscent of the \fBtermcap(5)\fR
4547file format; a colon-separated list of expressions of the form
4548"\fIxx=string\fR", where "\fIxx\fR" is a two-character variable name. The
4549variables with their associated defaults are:
4550.PP
4551.RS +8
4552.RS +4
4553.PD 0
4554.TP 12
4555no 0
4556Normal (non-filename) text
4557.TP 12
4558fi 0
4559Regular file
4560.TP 12
4561di 01;34
4562Directory
4563.TP 12
4564ln 01;36
4565Symbolic link
4566.TP 12
4567pi 33
4568Named pipe (FIFO)
4569.TP 12
4570so 01;35
4571Socket
4572.TP 12
4573bd 01;33
4574Block device
4575.TP 12
4576cd 01;32
4577Character device
4578.TP 12
4579ex 01;32
4580Executable file
4581.TP 12
4582mi (none)
4583Missing file (defaults to fi)
4584.TP 12
4585or (none)
4586Orphaned symbolic link (defaults to ln)
4587.TP 12
4588lc ^[[
4589Left code
4590.TP 12
4591rc m
4592Right code
4593.TP 12
4594ec (none)
4595End code (replaces lc+no+rc)
4596.PD
4597.RE
4598.PP
4599You need to include only the variables you want to change from
4600the default.
4601.PP
4602File names can also be colorized based on filename extension.
4603This is specified in the \fBLS_COLORS\fR variable using the syntax
4604\fB"*ext=string"\fR. For example, using ISO 6429 codes, to color
4605all C\-language source files blue you would specify \fB"*.c=34"\fR.
4606This would color all files ending in \fB.c\fR in blue (34) color.
4607.PP
4608Control characters can be written either in C\-style\-escaped
4609notation, or in stty\-like ^\-notation. The C\-style notation
4610adds \fB^[\fR for Escape, \fB\_\fR for a normal space character,
4611and \fB?\fR for Delete. In addition, the \fB^[\fR escape character
4612can be used to override the default interpretation of \fB^[\fR,
4613\fB^\fR, \fB:\fR and \fB=\fR.
4614.PP
4615Each file will be written as \fB<lc>\fR \fB<color-code>\fR
4616\fB<rc>\fR \fB<filename>\fR \fB<ec>\fR. If the \fB<ec>\fR
4617code is undefined, the sequence \fB<lc>\fR \fB<no>
4618\fB<rc>\fR will be used instead. This is generally more convenient
4619to use, but less general. The left, right and end codes are
4620provided so you don't have to type common parts over and over
4621again and to support weird terminals; you will generally not
4622need to change them at all unless your terminal does not use
4623ISO 6429 color sequences but a different system.
4624.PP
4625If your terminal does use ISO 6429 color codes, you can
4626compose the type codes (i.e., all except the \fBlc\fR, \fBrc\fR,
4627and \fBec\fR codes) from numerical commands separated by semicolons. The
4628most common commands are:
4629.PP
4630.RS +8
4631.PD 0
4632.TP 4
46330
4634to restore default color
4635.TP 4
46361
4637for brighter colors
4638.TP 4
46394
4640for underlined text
4641.TP 4
46425
4643for flashing text
4644.TP 4
464530
4646for black foreground
4647.TP 4
464831
4649for red foreground
4650.TP 4
465132
4652for green foreground
4653.TP 4
465433
4655for yellow (or brown) foreground
4656.TP 4
465734
4658for blue foreground
4659.TP 4
466035
4661for purple foreground
4662.TP 4
466336
4664for cyan foreground
4665.TP 4
466637
4667for white (or gray) foreground
4668.TP 4
466940
4670for black background
4671.TP 4
467241
4673for red background
4674.TP 4
467542
4676for green background
4677.TP 4
467843
4679for yellow (or brown) background
4680.TP 4
468144
4682for blue background
4683.TP 4
468445
4685for purple background
4686.TP 4
468746
4688for cyan background
4689.TP 4
469047
4691for white (or gray) background
4692.PD
4693.RE
4694.PP
4695Not all commands will work on all systems or display devices.
4696.PP
4697A few terminal programs do not recognize the default end code
4698properly. If all text gets colorized after you do a directory
4699listing, try changing the \fBno\fR and \fBfi\fR codes from 0 to the
4700numerical codes for your standard fore- and background colors.
4701.RE
4702.TP 8
4703.B MACHTYPE \fR(+)
4704The machine type (microprocessor class or machine model), as determined at compile time.
4705.TP 8
4706.B NOREBIND \fR(+)
4707If set, printable characters are not rebound to \fIself-insert-command\fR.
4708See \fBNative Language System support\fR.
4709.TP 8
4710.B OSTYPE \fR(+)
4711The operating system, as determined at compile time.
4712.TP 8
4713.B PATH
4714A colon-separated list of directories in which to look for executables.
4715Equivalent to the \fBpath\fR shell variable, but in a different format.
4716.TP 8
4717.B PWD \fR(+)
4718Equivalent to the \fBcwd\fR shell variable, but not synchronized to it;
4719updated only after an actual directory change.
4720.TP 8
4721.B REMOTEHOST \fR(+)
4722The host from which the user has logged in remotely, if this is the case and
4723the shell is able to determine it. Set only if the shell was so compiled;
4724see the \fBversion\fR shell variable.
4725.TP 8
4726.B SHLVL \fR(+)
4727Equivalent to the \fBshlvl\fR shell variable.
4728.TP 8
4729.B SYSTYPE \fR(+)
4730The current system type. (Domain/OS only)
4731.TP 8
4732.B TERM
4733Equivalent to the \fBterm\fR shell variable.
4734.TP 8
4735.B TERMCAP
4736The terminal capability string. See \fBTerminal management\fR.
4737.TP 8
4738.B USER
4739Equivalent to the \fBuser\fR shell variable.
4740.TP 8
4741.B VENDOR \fR(+)
4742The vendor, as determined at compile time.
4743.TP 8
4744.B VISUAL
4745The pathname to a default full-screen editor.
4746See also the \fBEDITOR\fR environment variable
4747and the \fIrun-fg-editor\fR editor command.
4748.SH FILES
4749.PD 0
4750.TP 16
4751.I /etc/csh.cshrc
4752Read first by every shell.
4753ConvexOS, Stellix and Intel use \fI/etc/cshrc\fR and
4754NeXTs use \fI/etc/cshrc.std\fR.
4755A/UX, AMIX, Cray and IRIX have no equivalent in \fIcsh\fR(1),
4756but read this file in \fItcsh\fR anyway.
4757Solaris 2.x does not have it either, but \fItcsh\fR reads \fI/etc/.cshrc\fR. (+)
4758.TP 16
4759.I /etc/csh.login
4760Read by login shells after \fI/etc/csh.cshrc\fR.
4761ConvexOS, Stellix and Intel use \fI/etc/login\fR,
4762NeXTs use \fI/etc/login.std\fR, Solaris 2.x uses \fI/etc/.login\fR and
4763A/UX, AMIX, Cray and IRIX use \fI/etc/cshrc\fR.
4764.TP 16
4765.I ~/.tcshrc \fR(+)
4766Read by every shell after \fI/etc/csh.cshrc\fR or its equivalent.
4767.TP 16
4768.I ~/.cshrc
4769Read by every shell, if \fI~/.tcshrc\fR doesn't exist,
4770after \fI/etc/csh.cshrc\fR or its equivalent.
4771This manual uses `\fI~/.tcshrc\fR' to mean `\fI~/.tcshrc\fR or,
4772if \fI~/.tcshrc\fR is not found, \fI~/.cshrc\fR'.
4773.TP 16
4774.I ~/.history
4775Read by login shells after \fI~/.tcshrc\fR
4776if \fBsavehist\fR is set, but see also \fBhistfile\fR.
4777.TP 16
4778.I ~/.login
4779Read by login shells after \fI~/.tcshrc\fR or \fI~/.history\fR.
4780The shell may be compiled to read \fI~/.login\fR before instead of after
4781\fI~/.tcshrc\fR and \fI~/.history\fR; see the \fBversion\fR shell variable.
4782.TP 16
4783.I ~/.cshdirs \fR(+)
4784Read by login shells after \fI~/.login\fR
4785if \fBsavedirs\fR is set, but see also \fBdirsfile\fR.
4786.TP 16
4787.I /etc/csh.logout
4788Read by login shells at logout.
4789ConvexOS, Stellix and Intel use \fI/etc/logout\fR and
4790NeXTs use \fI/etc/logout.std\fR.
4791A/UX, AMIX, Cray and IRIX have no equivalent in \fIcsh\fR(1),
4792but read this file in \fItcsh\fR anyway.
4793Solaris 2.x does not have it either, but \fItcsh\fR reads \fI/etc/.logout\fR. (+)
4794.TP 16
4795.I ~/.logout
4796Read by login shells at logout after \fI/etc/csh.logout\fR or its equivalent.
4797.TP 16
4798.I /bin/sh
4799Used to interpret shell scripts not starting with a `#'.
4800.TP 16
4801.I /tmp/sh*
4802Temporary file for `<<'.
4803.TP 16
4804.I /etc/passwd
4805Source of home directories for `~name' substitutions.
4806.PD
4807.PP
4808The order in which startup files are read may differ if the shell was so
4809compiled; see \fBStartup and shutdown\fR and the \fBversion\fR shell variable.
4810.SH "NEW FEATURES (+)"
4811This manual describes \fItcsh\fR as a single entity,
4812but experienced \fIcsh\fR(1) users will want to pay special attention to
4813\fItcsh\fR's new features.
4814.PP
4815A command-line editor, which supports GNU Emacs or \fIvi\fR(1)-style
4816key bindings. See \fBThe command-line editor\fR and \fBEditor commands\fR.
4817.PP
4818Programmable, interactive word completion and listing.
4819See \fBCompletion and listing\fR and the \fIcomplete\fR and \fIuncomplete\fR
4820builtin commands.
4821.PP
4822\fBSpelling correction\fR (q.v.) of filenames, commands and variables.
4823.PP
4824\fBEditor commands\fR (q.v.) which perform other useful functions in the middle of
4825typed commands, including documentation lookup (\fIrun-help\fR),
4826quick editor restarting (\fIrun-fg-editor\fR) and
4827command resolution (\fIwhich-command\fR).
4828.PP
4829An enhanced history mechanism. Events in the history list are time-stamped.
4830See also the \fIhistory\fR command and its associated shell variables,
4831the previously undocumented `#' event specifier and new modifiers
4832under \fBHistory substitution\fR,
4833the \fI*-history\fR, \fIhistory-search-*\fR, \fIi-search-*\fR, \fIvi-search-*\fR and
4834\fItoggle-literal-history\fR editor commands
4835and the \fBhistlit\fR shell variable.
4836.PP
4837Enhanced directory parsing and directory stack handling.
4838See the \fIcd\fR, \fIpushd\fR, \fIpopd\fR and \fIdirs\fR commands and their associated
4839shell variables, the description of \fBDirectory stack substitution\fR,
4840the \fBdirstack\fR, \fBowd\fR and \fBsymlinks\fR shell variables and
4841the \fInormalize-command\fR and \fInormalize-path\fR editor commands.
4842.PP
4843Negation in glob-patterns. See \fBFilename substitution\fR.
4844.PP
4845New \fBFile inquiry operators\fR (q.v.) and a \fIfiletest\fR
4846builtin which uses them.
4847.PP
4848A variety of \fBAutomatic, periodic and timed events\fR (q.v.) including
4849scheduled events, special aliases, automatic logout and terminal locking,
4850command timing and watching for logins and logouts.
4851.PP
4852Support for the Native Language System
4853(see \fBNative Language System support\fR),
4854OS variant features
4855(see \fBOS variant support\fR and the \fBecho_style\fR shell variable)
4856and system-dependent file locations (see \fBFILES\fR).
4857.PP
4858Extensive terminal-management capabilities. See \fBTerminal management\fR.
4859.PP
4860New builtin commands including \fIbuiltins\fR, \fIhup\fR, \fIls\-F\fR,
4861\fInewgrp\fR, \fIprintenv\fR, \fIwhich\fR and \fIwhere\fR (q.v.).
4862.PP
4863New variables that make useful information easily available to the shell.
4864See the \fBgid\fR, \fBloginsh\fR, \fBoid\fR, \fBshlvl\fR, \fBtcsh\fR,
4865\fBtty\fR, \fBuid\fR and \fBversion\fR shell variables and the \fBHOST\fR,
4866\fBREMOTEHOST\fR, \fBVENDOR\fR, \fBOSTYPE\fR and \fBMACHTYPE\fR environment
4867variables.
4868.PP
4869A new syntax for including useful information in the prompt string
4870(see \fBprompt\fR).
4871and special prompts for loops and spelling correction
4872(see \fBprompt2\fR and \fBprompt3\fR).
4873.PP
4874Read-only variables. See \fBVariable substitution\fR.
4875.SH BUGS
4876When a suspended command is restarted, the shell prints the directory
4877it started in if this is different from the current directory. This can
4878be misleading (i.e., wrong) as the job may have changed directories internally.
4879.PP
4880Shell builtin functions are not stoppable/restartable. Command sequences
4881of the form `a ; b ; c' are also not handled gracefully when stopping is
4882attempted. If you suspend `b', the shell will then immediately execute
4883`c'. This is especially noticeable if this expansion results from an
4884\fIalias\fR. It suffices to place the sequence of commands in ()'s to force it
4885to a subshell, i.e., `( a ; b ; c )'.
4886.PP
4887Control over tty output after processes are started is primitive; perhaps
4888this will inspire someone to work on a good virtual terminal interface.
4889In a virtual terminal interface much more interesting things could be
4890done with output control.
4891.PP
4892Alias substitution is most often used to clumsily simulate shell procedures;
4893shell procedures should be provided rather than aliases.
4894.PP
4895Commands within loops are not placed in the history
4896list. Control structures should be parsed rather than being recognized as
4897built-in commands. This would allow control commands to be placed anywhere,
4898to be combined with `|', and to be used with `&' and `;' metasyntax.
4899.PP
4900\fIforeach\fR doesn't ignore here documents when looking for its \fIend\fR.
4901.PP
4902It should be possible to use the `:' modifiers on the output of command
4903substitutions.
4904.PP
4905The screen update for lines longer than the screen width is very poor
4906if the terminal cannot move the cursor up (i.e., terminal type `dumb').
4907.PP
4908\fBHPATH\fR and \fBNOREBIND\fR don't need to be environment variables.
4909.PP
4910Glob-patterns which do not use `?', `*' or `[]' or which use `{}' or `~'
4911are not negated correctly.
4912.PP
4913The single-command form of \fIif\fR does output redirection even if
4914the expression is false and the command is not executed.
4915.PP
4916\fIls\-F\fR includes file identification characters when sorting filenames
4917and does not handle control characters in filenames well. It cannot be
4918interrupted.
4919.PP
4920Report bugs to tcsh-bugs@mx.gw.com, preferably with fixes. If you want to
4921help maintain and test tcsh, send mail to listserv@mx.gw.com with the text
4922`subscribe tcsh <your name>' on a line by itself in the body. You can
4923also `subscribe tcsh-bugs <your name>' to get all bug reports, or
4924`subscribe tcsh-diffs <your name>' to get the development list plus
4925diffs for each patchlevel.
4926.SH THE T IN TCSH
4927In 1964, DEC produced the PDP-6. The PDP-10 was a later re-implementation. It
4928was re-christened the DECsystem-10 in 1970 or so when DEC brought out the
4929second model, the KI10.
4930.PP
4931TENEX was created at Bolt, Beranek & Newman (a Cambridge, Massachusetts
4932think tank) in
49331972 as an experiment in demand-paged virtual memory operating systems. They
4934built a new pager for the DEC PDP-10 and created the OS to go with it. It was
4935extremely successful in academia.
4936.PP
4937In 1975, DEC brought out a new model of the PDP-10, the KL10; they intended to
4938have only a version of TENEX, which they had licensed from BBN, for the new
4939box. They called their version TOPS-20 (their capitalization is trademarked).
4940A lot of TOPS-10 users (`The OPerating System for PDP-10') objected; thus DEC
4941found themselves supporting two incompatible systems on the same hardware--but
4942then there were 6 on the PDP-11!
4943.PP
4944TENEX, and TOPS-20 to version 3, had command completion
4945via a user-code-level subroutine library called ULTCMD. With version 3, DEC
4946moved all that capability and more into the monitor (`kernel' for you Unix
4947types), accessed by the COMND% JSYS (`Jump to SYStem' instruction, the
4948supervisor call mechanism [are my IBM roots also showing?]).
4949.PP
4950The creator of tcsh was impressed by this feature and several others of TENEX
4951and TOPS-20, and created a version of csh which mimicked them.
4952.SH LIMITATIONS
4953Words can be no longer than 1024 characters.
4954.PP
4955The system limits argument lists to 10240 characters.
4956.PP
4957The number of arguments to a command which involves filename expansion is
4958limited to 1/6th the number of characters allowed in an argument list.
4959.PP
4960Command substitutions may substitute no more characters than are allowed in
4961an argument list.
4962.PP
4963To detect looping, the shell restricts the number of \fIalias\fR
4964substitutions on a single line to 20.
4965.SH "SEE ALSO"
4966csh(1), emacs(1), ls(1), newgrp(1), sh(1), setpath(1), stty(1), su(1),
4967tset(1), vi(1), x(1), access(2), execve(2), fork(2), killpg(2),
4968pipe(2), setrlimit(2), sigvec(2), stat(2), umask(2), vfork(2), wait(2),
4969malloc(3), setlocale(3), tty(4), a.out(5), termcap(5), environ(7),
4970termio(7), Introduction to the C Shell
4971.SH VERSION
| 4245.br
4246/tmp/to/dst
4247.br
4248> cd ".."; echo $cwd
4249.br
4250/tmp/from
4251.br
4252> /bin/echo ..
4253.br
4254/tmp/to
4255.br
4256> /bin/echo ".."
4257.br
4258\&..
4259.PP
4260Note that `expand' expansion 1) works just like `ignore' for builtins
4261like \fIcd\fR, 2) is prevented by quoting, and 3) happens before
4262filenames are passed to non-builtin commands.
4263.RE
4264.TP 8
4265.B tcsh \fR(+)
4266The version number of the shell in the format `R.VV.PP',
4267where `R' is the major release number, `VV' the current version
4268and `PP' the patchlevel.
4269.TP 8
4270.B term
4271The terminal type. Usually set in \fI~/.login\fR as described under
4272\fBStartup and shutdown\fR.
4273.TP 8
4274.B time
4275If set to a number, then the \fItime\fR builtin (q.v.) executes automatically
4276after each command which takes more than that many CPU seconds.
4277If there is a second word, it is used as a format string for the output
4278of the \fItime\fR builtin. (u) The following sequences may be used in the
4279format string:
4280.PP
4281.RS +8
4282.PD 0
4283.TP 4
4284%U
4285The time the process spent in user mode in cpu seconds.
4286.TP 4
4287%S
4288The time the process spent in kernel mode in cpu seconds.
4289.TP 4
4290%E
4291The elapsed (wall clock) time in seconds.
4292.TP 4
4293%P
4294The CPU percentage computed as (%U + %S) / %E.
4295.TP 4
4296%W
4297Number of times the process was swapped.
4298.TP 4
4299%X
4300The average amount in (shared) text space used in Kbytes.
4301.TP 4
4302%D
4303The average amount in (unshared) data/stack space used in Kbytes.
4304.TP 4
4305%K
4306The total space used (%X + %D) in Kbytes.
4307.TP 4
4308%M
4309The maximum memory the process had in use at any time in Kbytes.
4310.TP 4
4311%F
4312The number of major page faults (page needed to be brought from disk).
4313.TP 4
4314%R
4315The number of minor page faults.
4316.TP 4
4317%I
4318The number of input operations.
4319.TP 4
4320%O
4321The number of output operations.
4322.TP 4
4323%r
4324The number of socket messages received.
4325.TP 4
4326%s
4327The number of socket messages sent.
4328.TP 4
4329%k
4330The number of signals received.
4331.TP 4
4332%w
4333The number of voluntary context switches (waits).
4334.TP 4
4335%c
4336The number of involuntary context switches.
4337.PD
4338.PP
4339Only the first four sequences are supported on systems without BSD resource
4340limit functions.
4341The default time format is `%Uu %Ss %E %P %X+%Dk %I+%Oio %Fpf+%Ww' for
4342systems that support resource usage reporting and `%Uu %Ss %E %P' for
4343systems that do not.
4344.PP
4345Under Sequent's DYNIX/ptx, %X, %D, %K, %r and %s are not
4346available, but the following additional sequences are:
4347.PP
4348.PD 0
4349.TP 4
4350%Y
4351The number of system calls performed.
4352.TP 4
4353%Z
4354The number of pages which are zero-filled on demand.
4355.TP 4
4356%i
4357The number of times a process's resident set size was increased by the kernel.
4358.TP 4
4359%d
4360The number of times a process's resident set size was decreased by the kernel.
4361.TP 4
4362%l
4363The number of read system calls performed.
4364.TP 4
4365%m
4366The number of write system calls performed.
4367.TP 4
4368%p
4369The number of reads from raw disk devices.
4370.TP 4
4371%q
4372The number of writes to raw disk devices.
4373.PD
4374.PP
4375and the default time format is `%Uu %Ss $E %P %I+%Oio %Fpf+%Ww'.
4376Note that the CPU percentage can be higher than 100% on multi-processors.
4377.RE
4378.TP 8
4379.B tperiod \fR(+)
4380The period, in minutes, between executions of the \fIperiodic\fR special alias.
4381.TP 8
4382.B tty \fR(+)
4383The name of the tty, or empty if not attached to one.
4384.TP 8
4385.B uid \fR(+)
4386The user's real user ID.
4387.TP 8
4388.B user
4389The user's login name.
4390.TP 8
4391.B verbose
4392If set, causes the words of each
4393command to be printed, after history substitution (if any).
4394Set by the \fB\-v\fR command line option.
4395.TP 8
4396.B version \fR(+)
4397The version ID stamp. It contains the shell's version number (see \fBtcsh\fR),
4398origin, release date, vendor, operating system and machine (see \fBVENDOR\fR,
4399\fBOSTYPE\fR and \fBMACHTYPE\fR) and a comma-separated
4400list of options which were set at compile time.
4401Options which are set by default in the distribution are noted.
4402.PP
4403.RS +8
4404.PD 0
4405.TP 4
44068b
4407The shell is eight bit clean; default
4408.TP 4
44097b
4410The shell is not eight bit clean
4411.TP 4
4412nls
4413The system's NLS is used; default for systems with NLS
4414.TP 4
4415lf
4416Login shells execute \fI/etc/csh.login\fR before instead of after
4417\fI/etc/csh.cshrc\fR and \fI~/.login\fR before instead of after
4418\fI~/.tcshrc\fR and \fI~/.history\fR.
4419.TP 4
4420dl
4421`.' is put last in \fBpath\fR for security; default
4422.TP 4
4423nd
4424`.' is omitted from \fBpath\fR for security
4425.TP 4
4426vi
4427\fIvi\fR-style editing is the default rather than \fIemacs\fR
4428.TP 4
4429dtr
4430Login shells drop DTR when exiting
4431.TP 4
4432bye
4433\fIbye\fR is a synonym for \fIlogout\fR and \fIlog\fR
4434is an alternate name for \fIwatchlog\fR
4435.TP 4
4436al
4437\fBautologout\fR is enabled; default
4438.TP 4
4439kan
4440Kanji is used if appropriate according to locale settings,
4441unless the \fBnokanji\fR shell variable is set
4442.TP 4
4443sm
4444The system's \fImalloc\fR(3) is used
4445.TP 4
4446hb
4447The `#!<program> <args>' convention is emulated when executing shell scripts
4448.TP 4
4449ng
4450The \fInewgrp\fR builtin is available
4451.TP 4
4452rh
4453The shell attempts to set the \fBREMOTEHOST\fR environment variable
4454.TP 4
4455afs
4456The shell verifies your password with the kerberos server if local
4457authentication fails. The \fBafsuser\fR shell variable or the
4458\fBAFSUSER\fR environment variable override your local username if set.
4459.PD
4460.PP
4461An administrator may enter additional strings to indicate differences
4462in the local version.
4463.RE
4464.TP 8
4465.B visiblebell \fR(+)
4466If set, a screen flash is used rather than the audible bell.
4467See also \fBnobeep\fR.
4468.TP 8
4469.B watch \fR(+)
4470A list of user/terminal pairs to watch for logins and logouts.
4471If either the user is `any' all terminals are watched for the given user
4472and vice versa.
4473Setting \fBwatch\fR to `(any any)' watches all users and terminals.
4474For example,
4475.RS +8
4476.IP "" 4
4477set watch = (george ttyd1 any console $user any)
4478.PP
4479reports activity of the user `george' on ttyd1, any user on the console, and
4480oneself (or a trespasser) on any terminal.
4481.PP
4482Logins and logouts are checked every 10 minutes by default, but the first
4483word of \fBwatch\fR can be set to a number to check every so many minutes.
4484For example,
4485.IP "" 4
4486set watch = (1 any any)
4487.PP
4488reports any login/logout once every minute. For the impatient, the \fIlog\fR
4489builtin command triggers a \fBwatch\fR report at any time. All current logins
4490are reported (as with the \fIlog\fR builtin) when \fBwatch\fR is first set.
4491.PP
4492The \fBwho\fR shell variable controls the format of \fBwatch\fR reports.
4493.RE
4494.TP 8
4495.B who \fR(+)
4496The format string for \fBwatch\fR messages. The following sequences
4497are replaced by the given information:
4498.PP
4499.RS +8
4500.PD 0
4501.TP 4
4502%n
4503The name of the user who logged in/out.
4504.TP 4
4505%a
4506The observed action, i.e., `logged on', `logged off' or `replaced \fIolduser\fR on'.
4507.TP 4
4508%l
4509The terminal (tty) on which the user logged in/out.
4510.TP 4
4511%M
4512The full hostname of the remote host, or `local' if the login/logout was
4513from the local host.
4514.TP 4
4515%m
4516The hostname of the remote host up to the first `.'.
4517The full name is printed if it is an IP address or an X Window System display.
4518.PD
4519.PP
4520%M and %m are available on only systems that store the remote hostname in
4521\fI/etc/utmp\fR.
4522If unset, `%n has %a %l from %m.' is used, or `%n has %a %l.' on systems
4523which don't store the remote hostname.
4524.RE
4525.TP 8
4526.B wordchars \fR(+)
4527A list of non-alphanumeric characters to be considered part of a word by the
4528\fIforward-word\fR, \fIbackward-word\fR etc., editor commands.
4529If unset, `*?_\-.[]~=' is used.
4530.SH ENVIRONMENT
4531.TP 8
4532.B AFSUSER \fR(+)
4533Equivalent to the \fBafsuser\fR shell variable.
4534.TP 8
4535.B COLUMNS
4536The number of columns in the terminal. See \fBTerminal management\fR.
4537.TP 8
4538.B DISPLAY
4539Used by X Window System (see \fIX\fR(1)).
4540If set, the shell does not set \fBautologout\fR (q.v.).
4541.TP 8
4542.B EDITOR
4543The pathname to a default editor.
4544See also the \fBVISUAL\fR environment variable
4545and the \fIrun-fg-editor\fR editor command.
4546.TP 8
4547.B GROUP \fR(+)
4548Equivalent to the \fBgroup\fR shell variable.
4549.TP 8
4550.B HOME
4551Equivalent to the \fBhome\fR shell variable.
4552.TP 8
4553.B HOST \fR(+)
4554Initialized to the name of the machine on which the shell
4555is running, as determined by the \fIgethostname\fR(2) system call.
4556.TP 8
4557.B HOSTTYPE \fR(+)
4558Initialized to the type of machine on which the shell
4559is running, as determined at compile time. This variable is obsolete and
4560will be removed in a future version.
4561.TP 8
4562.B HPATH \fR(+)
4563A colon-separated list of directories in which the \fIrun-help\fR editor
4564command looks for command documentation.
4565.TP 8
4566.B LANG
4567Gives the preferred character environment.
4568See \fBNative Language System support\fR.
4569.TP 8
4570.B LC_CTYPE
4571If set, only ctype character handling is changed.
4572See \fBNative Language System support\fR.
4573.TP 8
4574.B LINES
4575The number of lines in the terminal. See \fBTerminal management\fR.
4576.TP 8
4577.B LS_COLORS
4578The format of this variable is reminiscent of the \fBtermcap(5)\fR
4579file format; a colon-separated list of expressions of the form
4580"\fIxx=string\fR", where "\fIxx\fR" is a two-character variable name. The
4581variables with their associated defaults are:
4582.PP
4583.RS +8
4584.RS +4
4585.PD 0
4586.TP 12
4587no 0
4588Normal (non-filename) text
4589.TP 12
4590fi 0
4591Regular file
4592.TP 12
4593di 01;34
4594Directory
4595.TP 12
4596ln 01;36
4597Symbolic link
4598.TP 12
4599pi 33
4600Named pipe (FIFO)
4601.TP 12
4602so 01;35
4603Socket
4604.TP 12
4605bd 01;33
4606Block device
4607.TP 12
4608cd 01;32
4609Character device
4610.TP 12
4611ex 01;32
4612Executable file
4613.TP 12
4614mi (none)
4615Missing file (defaults to fi)
4616.TP 12
4617or (none)
4618Orphaned symbolic link (defaults to ln)
4619.TP 12
4620lc ^[[
4621Left code
4622.TP 12
4623rc m
4624Right code
4625.TP 12
4626ec (none)
4627End code (replaces lc+no+rc)
4628.PD
4629.RE
4630.PP
4631You need to include only the variables you want to change from
4632the default.
4633.PP
4634File names can also be colorized based on filename extension.
4635This is specified in the \fBLS_COLORS\fR variable using the syntax
4636\fB"*ext=string"\fR. For example, using ISO 6429 codes, to color
4637all C\-language source files blue you would specify \fB"*.c=34"\fR.
4638This would color all files ending in \fB.c\fR in blue (34) color.
4639.PP
4640Control characters can be written either in C\-style\-escaped
4641notation, or in stty\-like ^\-notation. The C\-style notation
4642adds \fB^[\fR for Escape, \fB\_\fR for a normal space character,
4643and \fB?\fR for Delete. In addition, the \fB^[\fR escape character
4644can be used to override the default interpretation of \fB^[\fR,
4645\fB^\fR, \fB:\fR and \fB=\fR.
4646.PP
4647Each file will be written as \fB<lc>\fR \fB<color-code>\fR
4648\fB<rc>\fR \fB<filename>\fR \fB<ec>\fR. If the \fB<ec>\fR
4649code is undefined, the sequence \fB<lc>\fR \fB<no>
4650\fB<rc>\fR will be used instead. This is generally more convenient
4651to use, but less general. The left, right and end codes are
4652provided so you don't have to type common parts over and over
4653again and to support weird terminals; you will generally not
4654need to change them at all unless your terminal does not use
4655ISO 6429 color sequences but a different system.
4656.PP
4657If your terminal does use ISO 6429 color codes, you can
4658compose the type codes (i.e., all except the \fBlc\fR, \fBrc\fR,
4659and \fBec\fR codes) from numerical commands separated by semicolons. The
4660most common commands are:
4661.PP
4662.RS +8
4663.PD 0
4664.TP 4
46650
4666to restore default color
4667.TP 4
46681
4669for brighter colors
4670.TP 4
46714
4672for underlined text
4673.TP 4
46745
4675for flashing text
4676.TP 4
467730
4678for black foreground
4679.TP 4
468031
4681for red foreground
4682.TP 4
468332
4684for green foreground
4685.TP 4
468633
4687for yellow (or brown) foreground
4688.TP 4
468934
4690for blue foreground
4691.TP 4
469235
4693for purple foreground
4694.TP 4
469536
4696for cyan foreground
4697.TP 4
469837
4699for white (or gray) foreground
4700.TP 4
470140
4702for black background
4703.TP 4
470441
4705for red background
4706.TP 4
470742
4708for green background
4709.TP 4
471043
4711for yellow (or brown) background
4712.TP 4
471344
4714for blue background
4715.TP 4
471645
4717for purple background
4718.TP 4
471946
4720for cyan background
4721.TP 4
472247
4723for white (or gray) background
4724.PD
4725.RE
4726.PP
4727Not all commands will work on all systems or display devices.
4728.PP
4729A few terminal programs do not recognize the default end code
4730properly. If all text gets colorized after you do a directory
4731listing, try changing the \fBno\fR and \fBfi\fR codes from 0 to the
4732numerical codes for your standard fore- and background colors.
4733.RE
4734.TP 8
4735.B MACHTYPE \fR(+)
4736The machine type (microprocessor class or machine model), as determined at compile time.
4737.TP 8
4738.B NOREBIND \fR(+)
4739If set, printable characters are not rebound to \fIself-insert-command\fR.
4740See \fBNative Language System support\fR.
4741.TP 8
4742.B OSTYPE \fR(+)
4743The operating system, as determined at compile time.
4744.TP 8
4745.B PATH
4746A colon-separated list of directories in which to look for executables.
4747Equivalent to the \fBpath\fR shell variable, but in a different format.
4748.TP 8
4749.B PWD \fR(+)
4750Equivalent to the \fBcwd\fR shell variable, but not synchronized to it;
4751updated only after an actual directory change.
4752.TP 8
4753.B REMOTEHOST \fR(+)
4754The host from which the user has logged in remotely, if this is the case and
4755the shell is able to determine it. Set only if the shell was so compiled;
4756see the \fBversion\fR shell variable.
4757.TP 8
4758.B SHLVL \fR(+)
4759Equivalent to the \fBshlvl\fR shell variable.
4760.TP 8
4761.B SYSTYPE \fR(+)
4762The current system type. (Domain/OS only)
4763.TP 8
4764.B TERM
4765Equivalent to the \fBterm\fR shell variable.
4766.TP 8
4767.B TERMCAP
4768The terminal capability string. See \fBTerminal management\fR.
4769.TP 8
4770.B USER
4771Equivalent to the \fBuser\fR shell variable.
4772.TP 8
4773.B VENDOR \fR(+)
4774The vendor, as determined at compile time.
4775.TP 8
4776.B VISUAL
4777The pathname to a default full-screen editor.
4778See also the \fBEDITOR\fR environment variable
4779and the \fIrun-fg-editor\fR editor command.
4780.SH FILES
4781.PD 0
4782.TP 16
4783.I /etc/csh.cshrc
4784Read first by every shell.
4785ConvexOS, Stellix and Intel use \fI/etc/cshrc\fR and
4786NeXTs use \fI/etc/cshrc.std\fR.
4787A/UX, AMIX, Cray and IRIX have no equivalent in \fIcsh\fR(1),
4788but read this file in \fItcsh\fR anyway.
4789Solaris 2.x does not have it either, but \fItcsh\fR reads \fI/etc/.cshrc\fR. (+)
4790.TP 16
4791.I /etc/csh.login
4792Read by login shells after \fI/etc/csh.cshrc\fR.
4793ConvexOS, Stellix and Intel use \fI/etc/login\fR,
4794NeXTs use \fI/etc/login.std\fR, Solaris 2.x uses \fI/etc/.login\fR and
4795A/UX, AMIX, Cray and IRIX use \fI/etc/cshrc\fR.
4796.TP 16
4797.I ~/.tcshrc \fR(+)
4798Read by every shell after \fI/etc/csh.cshrc\fR or its equivalent.
4799.TP 16
4800.I ~/.cshrc
4801Read by every shell, if \fI~/.tcshrc\fR doesn't exist,
4802after \fI/etc/csh.cshrc\fR or its equivalent.
4803This manual uses `\fI~/.tcshrc\fR' to mean `\fI~/.tcshrc\fR or,
4804if \fI~/.tcshrc\fR is not found, \fI~/.cshrc\fR'.
4805.TP 16
4806.I ~/.history
4807Read by login shells after \fI~/.tcshrc\fR
4808if \fBsavehist\fR is set, but see also \fBhistfile\fR.
4809.TP 16
4810.I ~/.login
4811Read by login shells after \fI~/.tcshrc\fR or \fI~/.history\fR.
4812The shell may be compiled to read \fI~/.login\fR before instead of after
4813\fI~/.tcshrc\fR and \fI~/.history\fR; see the \fBversion\fR shell variable.
4814.TP 16
4815.I ~/.cshdirs \fR(+)
4816Read by login shells after \fI~/.login\fR
4817if \fBsavedirs\fR is set, but see also \fBdirsfile\fR.
4818.TP 16
4819.I /etc/csh.logout
4820Read by login shells at logout.
4821ConvexOS, Stellix and Intel use \fI/etc/logout\fR and
4822NeXTs use \fI/etc/logout.std\fR.
4823A/UX, AMIX, Cray and IRIX have no equivalent in \fIcsh\fR(1),
4824but read this file in \fItcsh\fR anyway.
4825Solaris 2.x does not have it either, but \fItcsh\fR reads \fI/etc/.logout\fR. (+)
4826.TP 16
4827.I ~/.logout
4828Read by login shells at logout after \fI/etc/csh.logout\fR or its equivalent.
4829.TP 16
4830.I /bin/sh
4831Used to interpret shell scripts not starting with a `#'.
4832.TP 16
4833.I /tmp/sh*
4834Temporary file for `<<'.
4835.TP 16
4836.I /etc/passwd
4837Source of home directories for `~name' substitutions.
4838.PD
4839.PP
4840The order in which startup files are read may differ if the shell was so
4841compiled; see \fBStartup and shutdown\fR and the \fBversion\fR shell variable.
4842.SH "NEW FEATURES (+)"
4843This manual describes \fItcsh\fR as a single entity,
4844but experienced \fIcsh\fR(1) users will want to pay special attention to
4845\fItcsh\fR's new features.
4846.PP
4847A command-line editor, which supports GNU Emacs or \fIvi\fR(1)-style
4848key bindings. See \fBThe command-line editor\fR and \fBEditor commands\fR.
4849.PP
4850Programmable, interactive word completion and listing.
4851See \fBCompletion and listing\fR and the \fIcomplete\fR and \fIuncomplete\fR
4852builtin commands.
4853.PP
4854\fBSpelling correction\fR (q.v.) of filenames, commands and variables.
4855.PP
4856\fBEditor commands\fR (q.v.) which perform other useful functions in the middle of
4857typed commands, including documentation lookup (\fIrun-help\fR),
4858quick editor restarting (\fIrun-fg-editor\fR) and
4859command resolution (\fIwhich-command\fR).
4860.PP
4861An enhanced history mechanism. Events in the history list are time-stamped.
4862See also the \fIhistory\fR command and its associated shell variables,
4863the previously undocumented `#' event specifier and new modifiers
4864under \fBHistory substitution\fR,
4865the \fI*-history\fR, \fIhistory-search-*\fR, \fIi-search-*\fR, \fIvi-search-*\fR and
4866\fItoggle-literal-history\fR editor commands
4867and the \fBhistlit\fR shell variable.
4868.PP
4869Enhanced directory parsing and directory stack handling.
4870See the \fIcd\fR, \fIpushd\fR, \fIpopd\fR and \fIdirs\fR commands and their associated
4871shell variables, the description of \fBDirectory stack substitution\fR,
4872the \fBdirstack\fR, \fBowd\fR and \fBsymlinks\fR shell variables and
4873the \fInormalize-command\fR and \fInormalize-path\fR editor commands.
4874.PP
4875Negation in glob-patterns. See \fBFilename substitution\fR.
4876.PP
4877New \fBFile inquiry operators\fR (q.v.) and a \fIfiletest\fR
4878builtin which uses them.
4879.PP
4880A variety of \fBAutomatic, periodic and timed events\fR (q.v.) including
4881scheduled events, special aliases, automatic logout and terminal locking,
4882command timing and watching for logins and logouts.
4883.PP
4884Support for the Native Language System
4885(see \fBNative Language System support\fR),
4886OS variant features
4887(see \fBOS variant support\fR and the \fBecho_style\fR shell variable)
4888and system-dependent file locations (see \fBFILES\fR).
4889.PP
4890Extensive terminal-management capabilities. See \fBTerminal management\fR.
4891.PP
4892New builtin commands including \fIbuiltins\fR, \fIhup\fR, \fIls\-F\fR,
4893\fInewgrp\fR, \fIprintenv\fR, \fIwhich\fR and \fIwhere\fR (q.v.).
4894.PP
4895New variables that make useful information easily available to the shell.
4896See the \fBgid\fR, \fBloginsh\fR, \fBoid\fR, \fBshlvl\fR, \fBtcsh\fR,
4897\fBtty\fR, \fBuid\fR and \fBversion\fR shell variables and the \fBHOST\fR,
4898\fBREMOTEHOST\fR, \fBVENDOR\fR, \fBOSTYPE\fR and \fBMACHTYPE\fR environment
4899variables.
4900.PP
4901A new syntax for including useful information in the prompt string
4902(see \fBprompt\fR).
4903and special prompts for loops and spelling correction
4904(see \fBprompt2\fR and \fBprompt3\fR).
4905.PP
4906Read-only variables. See \fBVariable substitution\fR.
4907.SH BUGS
4908When a suspended command is restarted, the shell prints the directory
4909it started in if this is different from the current directory. This can
4910be misleading (i.e., wrong) as the job may have changed directories internally.
4911.PP
4912Shell builtin functions are not stoppable/restartable. Command sequences
4913of the form `a ; b ; c' are also not handled gracefully when stopping is
4914attempted. If you suspend `b', the shell will then immediately execute
4915`c'. This is especially noticeable if this expansion results from an
4916\fIalias\fR. It suffices to place the sequence of commands in ()'s to force it
4917to a subshell, i.e., `( a ; b ; c )'.
4918.PP
4919Control over tty output after processes are started is primitive; perhaps
4920this will inspire someone to work on a good virtual terminal interface.
4921In a virtual terminal interface much more interesting things could be
4922done with output control.
4923.PP
4924Alias substitution is most often used to clumsily simulate shell procedures;
4925shell procedures should be provided rather than aliases.
4926.PP
4927Commands within loops are not placed in the history
4928list. Control structures should be parsed rather than being recognized as
4929built-in commands. This would allow control commands to be placed anywhere,
4930to be combined with `|', and to be used with `&' and `;' metasyntax.
4931.PP
4932\fIforeach\fR doesn't ignore here documents when looking for its \fIend\fR.
4933.PP
4934It should be possible to use the `:' modifiers on the output of command
4935substitutions.
4936.PP
4937The screen update for lines longer than the screen width is very poor
4938if the terminal cannot move the cursor up (i.e., terminal type `dumb').
4939.PP
4940\fBHPATH\fR and \fBNOREBIND\fR don't need to be environment variables.
4941.PP
4942Glob-patterns which do not use `?', `*' or `[]' or which use `{}' or `~'
4943are not negated correctly.
4944.PP
4945The single-command form of \fIif\fR does output redirection even if
4946the expression is false and the command is not executed.
4947.PP
4948\fIls\-F\fR includes file identification characters when sorting filenames
4949and does not handle control characters in filenames well. It cannot be
4950interrupted.
4951.PP
4952Report bugs to tcsh-bugs@mx.gw.com, preferably with fixes. If you want to
4953help maintain and test tcsh, send mail to listserv@mx.gw.com with the text
4954`subscribe tcsh <your name>' on a line by itself in the body. You can
4955also `subscribe tcsh-bugs <your name>' to get all bug reports, or
4956`subscribe tcsh-diffs <your name>' to get the development list plus
4957diffs for each patchlevel.
4958.SH THE T IN TCSH
4959In 1964, DEC produced the PDP-6. The PDP-10 was a later re-implementation. It
4960was re-christened the DECsystem-10 in 1970 or so when DEC brought out the
4961second model, the KI10.
4962.PP
4963TENEX was created at Bolt, Beranek & Newman (a Cambridge, Massachusetts
4964think tank) in
49651972 as an experiment in demand-paged virtual memory operating systems. They
4966built a new pager for the DEC PDP-10 and created the OS to go with it. It was
4967extremely successful in academia.
4968.PP
4969In 1975, DEC brought out a new model of the PDP-10, the KL10; they intended to
4970have only a version of TENEX, which they had licensed from BBN, for the new
4971box. They called their version TOPS-20 (their capitalization is trademarked).
4972A lot of TOPS-10 users (`The OPerating System for PDP-10') objected; thus DEC
4973found themselves supporting two incompatible systems on the same hardware--but
4974then there were 6 on the PDP-11!
4975.PP
4976TENEX, and TOPS-20 to version 3, had command completion
4977via a user-code-level subroutine library called ULTCMD. With version 3, DEC
4978moved all that capability and more into the monitor (`kernel' for you Unix
4979types), accessed by the COMND% JSYS (`Jump to SYStem' instruction, the
4980supervisor call mechanism [are my IBM roots also showing?]).
4981.PP
4982The creator of tcsh was impressed by this feature and several others of TENEX
4983and TOPS-20, and created a version of csh which mimicked them.
4984.SH LIMITATIONS
4985Words can be no longer than 1024 characters.
4986.PP
4987The system limits argument lists to 10240 characters.
4988.PP
4989The number of arguments to a command which involves filename expansion is
4990limited to 1/6th the number of characters allowed in an argument list.
4991.PP
4992Command substitutions may substitute no more characters than are allowed in
4993an argument list.
4994.PP
4995To detect looping, the shell restricts the number of \fIalias\fR
4996substitutions on a single line to 20.
4997.SH "SEE ALSO"
4998csh(1), emacs(1), ls(1), newgrp(1), sh(1), setpath(1), stty(1), su(1),
4999tset(1), vi(1), x(1), access(2), execve(2), fork(2), killpg(2),
5000pipe(2), setrlimit(2), sigvec(2), stat(2), umask(2), vfork(2), wait(2),
5001malloc(3), setlocale(3), tty(4), a.out(5), termcap(5), environ(7),
5002termio(7), Introduction to the C Shell
5003.SH VERSION
|
4972This manual documents tcsh 6.10.00 (Astron) 2000-11-19.
| 5004This manual documents tcsh 6.11.00 (Astron) 2001-09-02.
|
4973.SH AUTHORS
4974.PD 0
4975.TP 2
4976William Joy
4977Original author of \fIcsh\fR(1)
4978.TP 2
4979J.E. Kulp, IIASA, Laxenburg, Austria
4980Job control and directory stack features
4981.TP 2
4982Ken Greer, HP Labs, 1981
4983File name completion
4984.TP 2
4985Mike Ellis, Fairchild, 1983
4986Command name recognition/completion
4987.TP 2
4988Paul Placeway, Ohio State CIS Dept., 1983-1993
4989Command line editor, prompt routines, new glob syntax and numerous fixes
4990and speedups
4991.TP 2
4992Karl Kleinpaste, CCI 1983-4
4993Special aliases, directory stack extraction stuff, login/logout watch,
4994scheduled events, and the idea of the new prompt format
4995.TP 2
4996Rayan Zachariassen, University of Toronto, 1984
4997\fIls\-F\fR and \fIwhich\fR builtins and numerous bug fixes, modifications
4998and speedups
4999.TP 2
5000Chris Kingsley, Caltech
5001Fast storage allocator routines
5002.TP 2
5003Chris Grevstad, TRW, 1987
5004Incorporated 4.3BSD \fIcsh\fR into \fItcsh\fR
5005.TP 2
5006Christos S. Zoulas, Cornell U. EE Dept., 1987-94
5007Ports to HPUX, SVR2 and SVR3, a SysV version of getwd.c, SHORT_STRINGS support
5008and a new version of sh.glob.c
5009.TP 2
5010James J Dempsey, BBN, and Paul Placeway, OSU, 1988
5011A/UX port
5012.TP 2
5013Daniel Long, NNSC, 1988
5014\fBwordchars\fR
5015.TP 2
5016Patrick Wolfe, Kuck and Associates, Inc., 1988
5017\fIvi\fR mode cleanup
5018.TP 2
5019David C Lawrence, Rensselaer Polytechnic Institute, 1989
5020\fBautolist\fR and ambiguous completion listing
5021.TP 2
5022Alec Wolman, DEC, 1989
5023Newlines in the prompt
5024.TP 2
5025Matt Landau, BBN, 1989
5026\fI~/.tcshrc\fR
5027.TP 2
5028Ray Moody, Purdue Physics, 1989
5029Magic space bar history expansion
5030.TP 2
5031Mordechai ????, Intel, 1989
5032printprompt() fixes and additions
5033.TP 2
5034Kazuhiro Honda, Dept. of Computer Science, Keio University, 1989
5035Automatic spelling correction and \fBprompt3\fR
5036.TP 2
5037Per Hedeland, Ellemtel, Sweden, 1990-
5038Various bugfixes, improvements and manual updates
5039.TP 2
5040Hans J. Albertsson (Sun Sweden)
5041\fBampm\fR, \fIsettc\fR and \fItelltc\fR
5042.TP 2
5043Michael Bloom
5044Interrupt handling fixes
5045.TP 2
5046Michael Fine, Digital Equipment Corp
5047Extended key support
5048.TP 2
5049Eric Schnoebelen, Convex, 1990
5050Convex support, lots of \fIcsh\fR bug fixes,
5051save and restore of directory stack
5052.TP 2
5053Ron Flax, Apple, 1990
5054A/UX 2.0 (re)port
5055.TP 2
5056Dan Oscarsson, LTH Sweden, 1990
5057NLS support and simulated NLS support for non NLS sites, fixes
5058.TP 2
5059Johan Widen, SICS Sweden, 1990
5060\fBshlvl\fR, Mach support, \fIcorrect-line\fR, 8-bit printing
5061.TP 2
5062Matt Day, Sanyo Icon, 1990
5063POSIX termio support, SysV limit fixes
5064.TP 2
5065Jaap Vermeulen, Sequent, 1990-91
5066Vi mode fixes, expand-line, window change fixes, Symmetry port
5067.TP 2
5068Martin Boyer, Institut de recherche d'Hydro-Quebec, 1991
5069\fBautolist\fR beeping options, modified the history search to search for
5070the whole string from the beginning of the line to the cursor.
5071.TP 2
5072Scott Krotz, Motorola, 1991
5073Minix port
5074.TP 2
5075David Dawes, Sydney U. Australia, Physics Dept., 1991
5076SVR4 job control fixes
5077.TP 2
5078Jose Sousa, Interactive Systems Corp., 1991
5079Extended \fIvi\fR fixes and \fIvi\fR delete command
5080.TP 2
5081Marc Horowitz, MIT, 1991
5082ANSIfication fixes, new exec hashing code, imake fixes, \fIwhere\fR
5083.TP 2
5084Bruce Sterling Woodcock, sterling@netcom.com, 1991-1995
5085ETA and Pyramid port, Makefile and lint fixes, \fBignoreeof\fR=n addition, and
5086various other portability changes and bug fixes
5087.TP 2
5088Jeff Fink, 1992
5089\fIcomplete-word-fwd\fR and \fIcomplete-word-back\fR
5090.TP 2
5091Harry C. Pulley, 1992
5092Coherent port
5093.TP 2
5094Andy Phillips, Mullard Space Science Lab U.K., 1992
5095VMS-POSIX port
5096.TP 2
5097Beto Appleton, IBM Corp., 1992
5098Walking process group fixes, \fIcsh\fR bug fixes,
5099POSIX file tests, POSIX SIGHUP
5100.TP 2
5101Scott Bolte, Cray Computer Corp., 1992
5102CSOS port
5103.TP 2
5104Kaveh R. Ghazi, Rutgers University, 1992
5105Tek, m88k, Titan and Masscomp ports and fixes. Added autoconf support.
5106.TP 2
5107Mark Linderman, Cornell University, 1992
5108OS/2 port
5109.TP 2
5110Mika Liljeberg, liljeber@kruuna.Helsinki.FI, 1992
5111Linux port
5112.TP 2
5113Tim P. Starrin, NASA Langley Research Center Operations, 1993
5114Read-only variables
5115.TP 2
5116Dave Schweisguth, Yale University, 1993-4
5117New man page and tcsh.man2html
5118.TP 2
5119Larry Schwimmer, Stanford University, 1993
5120AFS and HESIOD patches
5121.TP 2
5122Luke Mewburn, RMIT University, 1994-6
5123Enhanced directory printing in prompt,
5124added \fBellipsis\fR and \fBrprompt\fR.
5125.TP 2
5126Edward Hutchins, Silicon Graphics Inc., 1996
5127Added implicit cd.
5128.TP 2
5129Martin Kraemer, 1997
5130Ported to Siemens Nixdorf EBCDIC machine
5131.TP 2
5132Amol Deshpande, Microsoft, 1997
5133Ported to WIN32 (Windows/95 and Windows/NT); wrote all the missing library
5134and message catalog code to interface to Windows.
5135.TP 2
5136Taga Nayuta, 1998
5137Color ls additions.
5138.PD
5139.PP
5140.SH "THANKS TO"
5141Bryan Dunlap, Clayton Elwell, Karl Kleinpaste, Bob Manson, Steve Romig,
5142Diana Smetters, Bob Sutterfield, Mark Verber, Elizabeth Zwicky and all
5143the other people at Ohio State for suggestions and encouragement
5144.PP
5145All the people on the net, for putting up with,
5146reporting bugs in, and suggesting new additions to each and every version
5147.PP
5148Richard M. Alderson III, for writing the `T in tcsh' section
| 5005.SH AUTHORS
5006.PD 0
5007.TP 2
5008William Joy
5009Original author of \fIcsh\fR(1)
5010.TP 2
5011J.E. Kulp, IIASA, Laxenburg, Austria
5012Job control and directory stack features
5013.TP 2
5014Ken Greer, HP Labs, 1981
5015File name completion
5016.TP 2
5017Mike Ellis, Fairchild, 1983
5018Command name recognition/completion
5019.TP 2
5020Paul Placeway, Ohio State CIS Dept., 1983-1993
5021Command line editor, prompt routines, new glob syntax and numerous fixes
5022and speedups
5023.TP 2
5024Karl Kleinpaste, CCI 1983-4
5025Special aliases, directory stack extraction stuff, login/logout watch,
5026scheduled events, and the idea of the new prompt format
5027.TP 2
5028Rayan Zachariassen, University of Toronto, 1984
5029\fIls\-F\fR and \fIwhich\fR builtins and numerous bug fixes, modifications
5030and speedups
5031.TP 2
5032Chris Kingsley, Caltech
5033Fast storage allocator routines
5034.TP 2
5035Chris Grevstad, TRW, 1987
5036Incorporated 4.3BSD \fIcsh\fR into \fItcsh\fR
5037.TP 2
5038Christos S. Zoulas, Cornell U. EE Dept., 1987-94
5039Ports to HPUX, SVR2 and SVR3, a SysV version of getwd.c, SHORT_STRINGS support
5040and a new version of sh.glob.c
5041.TP 2
5042James J Dempsey, BBN, and Paul Placeway, OSU, 1988
5043A/UX port
5044.TP 2
5045Daniel Long, NNSC, 1988
5046\fBwordchars\fR
5047.TP 2
5048Patrick Wolfe, Kuck and Associates, Inc., 1988
5049\fIvi\fR mode cleanup
5050.TP 2
5051David C Lawrence, Rensselaer Polytechnic Institute, 1989
5052\fBautolist\fR and ambiguous completion listing
5053.TP 2
5054Alec Wolman, DEC, 1989
5055Newlines in the prompt
5056.TP 2
5057Matt Landau, BBN, 1989
5058\fI~/.tcshrc\fR
5059.TP 2
5060Ray Moody, Purdue Physics, 1989
5061Magic space bar history expansion
5062.TP 2
5063Mordechai ????, Intel, 1989
5064printprompt() fixes and additions
5065.TP 2
5066Kazuhiro Honda, Dept. of Computer Science, Keio University, 1989
5067Automatic spelling correction and \fBprompt3\fR
5068.TP 2
5069Per Hedeland, Ellemtel, Sweden, 1990-
5070Various bugfixes, improvements and manual updates
5071.TP 2
5072Hans J. Albertsson (Sun Sweden)
5073\fBampm\fR, \fIsettc\fR and \fItelltc\fR
5074.TP 2
5075Michael Bloom
5076Interrupt handling fixes
5077.TP 2
5078Michael Fine, Digital Equipment Corp
5079Extended key support
5080.TP 2
5081Eric Schnoebelen, Convex, 1990
5082Convex support, lots of \fIcsh\fR bug fixes,
5083save and restore of directory stack
5084.TP 2
5085Ron Flax, Apple, 1990
5086A/UX 2.0 (re)port
5087.TP 2
5088Dan Oscarsson, LTH Sweden, 1990
5089NLS support and simulated NLS support for non NLS sites, fixes
5090.TP 2
5091Johan Widen, SICS Sweden, 1990
5092\fBshlvl\fR, Mach support, \fIcorrect-line\fR, 8-bit printing
5093.TP 2
5094Matt Day, Sanyo Icon, 1990
5095POSIX termio support, SysV limit fixes
5096.TP 2
5097Jaap Vermeulen, Sequent, 1990-91
5098Vi mode fixes, expand-line, window change fixes, Symmetry port
5099.TP 2
5100Martin Boyer, Institut de recherche d'Hydro-Quebec, 1991
5101\fBautolist\fR beeping options, modified the history search to search for
5102the whole string from the beginning of the line to the cursor.
5103.TP 2
5104Scott Krotz, Motorola, 1991
5105Minix port
5106.TP 2
5107David Dawes, Sydney U. Australia, Physics Dept., 1991
5108SVR4 job control fixes
5109.TP 2
5110Jose Sousa, Interactive Systems Corp., 1991
5111Extended \fIvi\fR fixes and \fIvi\fR delete command
5112.TP 2
5113Marc Horowitz, MIT, 1991
5114ANSIfication fixes, new exec hashing code, imake fixes, \fIwhere\fR
5115.TP 2
5116Bruce Sterling Woodcock, sterling@netcom.com, 1991-1995
5117ETA and Pyramid port, Makefile and lint fixes, \fBignoreeof\fR=n addition, and
5118various other portability changes and bug fixes
5119.TP 2
5120Jeff Fink, 1992
5121\fIcomplete-word-fwd\fR and \fIcomplete-word-back\fR
5122.TP 2
5123Harry C. Pulley, 1992
5124Coherent port
5125.TP 2
5126Andy Phillips, Mullard Space Science Lab U.K., 1992
5127VMS-POSIX port
5128.TP 2
5129Beto Appleton, IBM Corp., 1992
5130Walking process group fixes, \fIcsh\fR bug fixes,
5131POSIX file tests, POSIX SIGHUP
5132.TP 2
5133Scott Bolte, Cray Computer Corp., 1992
5134CSOS port
5135.TP 2
5136Kaveh R. Ghazi, Rutgers University, 1992
5137Tek, m88k, Titan and Masscomp ports and fixes. Added autoconf support.
5138.TP 2
5139Mark Linderman, Cornell University, 1992
5140OS/2 port
5141.TP 2
5142Mika Liljeberg, liljeber@kruuna.Helsinki.FI, 1992
5143Linux port
5144.TP 2
5145Tim P. Starrin, NASA Langley Research Center Operations, 1993
5146Read-only variables
5147.TP 2
5148Dave Schweisguth, Yale University, 1993-4
5149New man page and tcsh.man2html
5150.TP 2
5151Larry Schwimmer, Stanford University, 1993
5152AFS and HESIOD patches
5153.TP 2
5154Luke Mewburn, RMIT University, 1994-6
5155Enhanced directory printing in prompt,
5156added \fBellipsis\fR and \fBrprompt\fR.
5157.TP 2
5158Edward Hutchins, Silicon Graphics Inc., 1996
5159Added implicit cd.
5160.TP 2
5161Martin Kraemer, 1997
5162Ported to Siemens Nixdorf EBCDIC machine
5163.TP 2
5164Amol Deshpande, Microsoft, 1997
5165Ported to WIN32 (Windows/95 and Windows/NT); wrote all the missing library
5166and message catalog code to interface to Windows.
5167.TP 2
5168Taga Nayuta, 1998
5169Color ls additions.
5170.PD
5171.PP
5172.SH "THANKS TO"
5173Bryan Dunlap, Clayton Elwell, Karl Kleinpaste, Bob Manson, Steve Romig,
5174Diana Smetters, Bob Sutterfield, Mark Verber, Elizabeth Zwicky and all
5175the other people at Ohio State for suggestions and encouragement
5176.PP
5177All the people on the net, for putting up with,
5178reporting bugs in, and suggesting new additions to each and every version
5179.PP
5180Richard M. Alderson III, for writing the `T in tcsh' section
|