2 .\" Copyright (c) 1980, 1990, 1993
3 .\" The Regents of the University of California. All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\" 3. Neither the name of the University nor the names of its contributors
14 .\" may be used to endorse or promote products derived from this software
15 .\" without specific prior written permission.
17 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS `AS IS' AND
18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23 .\" OR SERVICES; LESS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 .\" - Indent in multiples of 4, usually 8.
31 .\" - Use \` for literal back-quote (`).
33 .\" - Use \e for literal backslash (\).
37 .\" - Include the tilde when naming dot files. .Pa ~/.login , not .Pa .login
39 .\" - Refer to external commands in man page format, e.g., .Xr csh 1
40 .\" However, tcsh is .Nm , because this is the tcsh man page (and
41 .\" see the next note anyway).
43 .\" - Say .Sq the shell , not .Sq tcsh ,
44 .\" unless distinguishing between tcsh and csh.
46 .\" - Say .Sq shell variable / .Sq environment variable instead of
47 .\" .Sq variable and .Sq builtin command / .Sq editor command instead of
48 .\" .Sq builtin or .Sq command
49 .\" unless the distinction is absolutely clear from context.
51 .\" - Use the simple present tense.
52 .\" .Sq The shell uses , not .Sq The shell will use
54 .\" - IMPORTANT: Cross-reference as much as possible. Commands, variables,
55 .\" etc. in the reference section should be mentioned in the appropriate
56 .\" descriptive section, or at least in the reference-section description
57 .\" of another command (or whatever) which is mentioned in a description
58 .\" section. Remember to note OS-specific things in "OS variant support",
59 .\" new features in NEW FEATURES and referenced external commands in SEE
62 .\" - tcsh.man2html depends heavily on the specific nroff commands used in the
63 .\" man page when the script was written. Please stick closely to the style
64 .\" used here if you can. In particular, please don't use nroff commands
65 .\" which aren't already used herein.
72 .Nd C shell with file name completion and command line editing
75 .Op Fl bcdefFimnqstvVxX
76 .Op Fl Dname Ns Op =value
83 is an enhanced but completely compatible version of the Berkeley
86 It is a command language interpreter usable both as an interactive login
87 shell and a shell script command processor.
88 It includes a command-line editor (see
89 .Sx The command-line editor )
90 programmable word completion (see
91 .Sx Completion and listing )
92 spelling correction (see
93 .Sx Spelling correction ) ,
94 a history mechanism (see
95 .Sx History substitution ) ,
101 section describes major enhancements of
105 Throughout this manual, features of
110 (specifically, the 4.4BSD one)
113 and features which are present in
115 but not usually documented are labeled with
118 .Ss Argument list processing
119 If the first argument (argument 0) to the shell is
121 then it is a login shell.
122 A login shell can be also specified by invoking the shell with
125 flag as the only argument.
127 The rest of the flag arguments are interpreted as follows:
128 .Bl -tag -width indent
132 from option processing, causing any
133 further shell arguments to be treated as non-option arguments.
134 The remaining arguments will not be interpreted as shell options.
135 This may be used to pass options to a shell script without confusion
136 or possible subterfuge.
137 The shell will not run a set-user ID script without this option.
139 Commands are read from the following argument (which must be present, and
140 must be a single argument),
143 shell variable for reference, and executed.
144 Any remaining arguments are placed in the
148 The shell loads the directory stack from
151 .Sx Startup and shutdown ,
152 whether or not it is a login shell. (+)
153 .It Fl Dname Ns Op =value
154 Sets the environment variable
159 The shell exits if any invoked command terminates abnormally or
160 yields a non-zero exit status.
162 The shell does not load any resource or startup files, or perform any
163 command hashing, and thus starts faster.
169 to spawn processes. (+)
171 The shell is interactive and prompts for its top-level input, even if
172 it appears to not be a terminal.
173 Shells are interactive without this option if
174 their inputs and outputs are terminals.
176 The shell is a login shell.
184 even if it does not belong to the effective user.
191 The shell parses commands but does not execute them.
192 This aids in debugging shell scripts.
194 The shell accepts SIGQUIT (see
195 .Sx Signal handling )
196 and behaves when it is used under a debugger.
197 Job control is disabled. (u)
199 Command input is taken from the standard input.
201 The shell reads and executes a single line of input.
205 escape the newline at the end of this line and continue onto another line.
209 shell variable, so that
210 command input is echoed after history substitution.
214 shell variable, so that commands are echoed
215 immediately before execution.
219 shell variable even before executing
230 Print a help message on the standard output and exit. (+)
232 Print the version/platform/compilation options on the standard output and exit.
233 This information is also contained in the
238 After processing of flag arguments, if arguments remain but none of the
244 options were given, the first argument is taken as the name of a file of
248 The shell opens this file and saves its name for possible
251 Because many systems use either the standard
252 version 6 or version 7 shells whose shell scripts are not compatible
253 with this shell, the shell uses such a
255 shell to execute a script
256 whose first character is not a
258 i.e., that does not start with a
261 Remaining arguments are placed in the
264 .Ss Startup and shutdown
265 A login shell begins by executing commands from the system files
269 It then executes commands from files in the user's
282 shell variable), then
291 before instead of after
295 before instead of after
306 Non-login shells read only
314 For examples of startup files, please consult:
315 .Lk http://tcshrc.sourceforge.net
321 which need be run only once per login, usually go in one's
324 Users who need to use the same set of files with both
330 which checks for the existence of the
332 shell variable (q.v.) before using
341 (see the builtin command)
343 The rest of this manual uses
353 In the normal case, the shell begins reading commands from the terminal,
356 (Processing of arguments and the use of the shell to
357 process files containing command scripts are described later.)
358 The shell repeatedly reads a line of command input, breaks it into words,
359 places it on the command history list, parses it and executes each command
362 One can log out by typing
369 via the shell's autologout mechanism (see the
372 When a login shell terminates it sets the
378 as appropriate, then executes commands from the files
382 The shell may drop DTR on logout
383 if so compiled; see the
387 The names of the system login and logout files vary from system to system for
388 compatibility with different
394 .Sx The command-line editor"
396 .Sx Completion and listing
398 .Sx Spelling correction
399 sections describe two sets of functionality that are implemented as editor
400 commands but which deserve their own treatment.
404 the editor commands specific to the shell and their default bindings.
405 .It Sx The command-line editor (+)
406 Command-line input can be edited using key sequences much like those used in
410 The editor is active only when the
412 shell variable is set, which it is by default in interactive shells.
415 builtin can display and change key bindings.
417 style key bindings are used by default
418 (unless the shell was compiled otherwise; see the
423 can change the key bindings to
425 style bindings en masse.
427 The shell always binds the arrow keys (as defined in the
429 environment variable) to:
431 .Bl -tag -width right -compact -offset indent
442 unless doing so would alter another single-character binding.
443 One can set the arrow key escape sequences to the empty string with
445 to prevent these bindings.
446 The ANSI/VT100 sequences for arrow keys are always bound.
448 Other key bindings are, for the most part, what
452 users would expect and can easily be displayed by
455 is no need to list them here.
459 commands with a short description of each.
460 Certain key bindings have different behavior depending if
464 style bindings are being used; see
466 for more information.
468 Note that editor commands do not have the same notion of a
471 The editor delimits words with any non-alphanumeric characters not in
474 while the shell recognizes only whitespace
475 and some of the characters with special meanings to it, listed under
476 .Sx Lexical structure .
477 .Ss Completion and listing (+)
478 The shell is often able to complete words when given a unique abbreviation.
479 Type part of a word (for example
482 and hit the tab key to run the
485 The shell completes the filename
488 .Pa /usr/lost+found/ ,
489 replacing the incomplete word with the complete word in the input buffer.
494 to the end of completed directories and a space to the end of other completed
495 words, to speed typing and provide a visual indicator of successful completion.
498 shell variable can be unset to prevent this.)
499 If no match is found (perhaps
501 doesn't exist), the terminal bell rings.
502 If the word is already complete (perhaps there is a
505 system, or perhaps you were thinking too far ahead and typed the whole thing)
508 or space is added to the end if it isn't already there.
510 Completion works anywhere in the line, not at just the end; completed
511 text pushes the rest of the line to the right.
512 Completion in the middle of a word
513 often results in leftover characters to the right of the cursor that need
516 Commands and variables can be completed in much the same way.
525 were the only command on your system beginning with
527 Completion can find a command in any directory in
529 or if given a full pathname.
536 if no other variable began with
539 The shell parses the input buffer to determine whether the word you want to
540 complete should be completed as a filename, command or variable.
541 The first word in the buffer and the first word following
548 is considered to be a command.
549 A word beginning with
551 is considered to be a variable.
552 Anything else is a filename.
557 You can list the possible completions of a word at any time by typing
560 .Ic delete-char-or-list-or-eof
562 The shell lists the possible completions using the
565 and reprints the prompt and unfinished command line, for example:
566 .Bd -literal -offset indent
568 lbin/ lib/ local/ lost+found/
574 shell variable is set, the shell lists the remaining
575 choices (if any) whenever completion fails:
576 .Bd -literal -offset indent
578 > nm /usr/lib/libt[tab]
579 libtermcap.a@ libtermlib.a@
580 > nm /usr/lib/libterm
585 shell variable is set to
587 choices are listed only when
588 completion fails and adds no new characters to the word being completed.
590 A filename to be completed can contain variables, your own or others' home
591 directories abbreviated with
594 .Sx Filename substitution )
595 and directory stack entries abbreviated with
598 .Sx Directory stack substitution ) .
600 .Bd -literal -offset indent
607 .Bd -literal -offset indent
608 > set local = /usr/local
611 bin/ etc/ lib/ man/ src/
615 Note that variables can also be expanded explicitly with the
619 .Ic delete-char-or-list-or-eof
620 lists at only the end of the line;
621 in the middle of a line it deletes the character under the cursor and
622 on an empty line it logs one out or, if then
624 variable is set, does nothing.
626 bound to the editor command
629 possibilities anywhere on a line, and
632 related editor commands that do or don't delete, list and/or log out,
634 .Ic delete-char-or-list-or-eof )
639 builtin command if so desired.
642 .Ic complete-word-fwd
644 .Ic complete-word-back
646 (not bound to any keys by default) can be used to cycle up and down through
647 the list of possible completions, replacing the current word with the next or
648 previous word in the list.
652 can be set to a list of suffixes to be ignored by completion.
653 Consider the following:
654 .Bd -literal -offset indent
656 Makefile condiments.h~ main.o side.c
657 README main.c meal side.o
659 > set fignore = (.o \e~)
661 main.c main.c~ main.o
669 are ignored by completion (but not listing),
670 because they end in suffixes in
674 was needed in front of
676 to prevent it from being expanded to
679 .Sx Filename substitution .
681 is ignored if only one completion is possible.
685 shell variable is set to
688 1) ignores case and 2) considers periods, hyphens and underscores
693 to be word separators and hyphens and underscores to be equivalent.
694 If you had the following files
695 .Bd -literal -offset indent
696 comp.lang.c comp.lang.perl comp.std.c++
697 comp.lang.c++ comp.std.c
701 .Sq mail \-f c.l.c[tab] ,
702 it would be completed to
703 .Sq mail \-f comp.lang.c ,
710 .Sq mail \-f c..c++[^D]
717 in the following directory
718 .Bd -literal -offset indent
719 A_silly_file a-hyphenated-file another_silly_file
722 would list all three files, because case is ignored and hyphens and
723 underscores are equivalent.
724 Periods, however, are not equivalent to
725 hyphens or underscores.
729 shell variable is set to
732 ignores case and differences between a hyphen and an underscore word
733 separator only when the user types a lowercase character or a hyphen.
734 Entering an uppercase character or an underscore will not match the
735 corresponding lowercase character or hyphen word separator.
738 in the directory of the previous example would
739 still list all three files, but typing
748 .Sq another_silly_file
749 because the user explicitly used an uppercase
750 or an underscore character.
752 Completion and listing are affected by several other shell variables:
754 can be set to complete on the shortest possible unique
755 match, even if more typing might result in a longer match:
756 .Bd -literal -offset indent
758 fodder foo food foonly
769 but if we type another
771 .Bd -literal -offset indent
776 the completion completes on
784 can be set to run the
787 before each completion attempt,
790 spelling-correct the word to be completed (see
791 .Sx Spelling correction )
792 before each completion attempt and
794 can be set to complete commands automatically after one hits
797 can be set to make completion beep or not beep in a variety
800 can be set to never beep at all.
802 can be set to a list of directories and/or patterns that
803 match directories to prevent the completion mechanism from
810 can be set to limit the number of items
811 and rows (respectively) that are listed without asking first.
812 .Va recognize_only_executables
813 can be set to make the shell list only
814 executables when listing commands, but it is quite slow.
818 builtin command can be used to tell the shell how
819 to complete words other than filenames, commands and variables.
820 Completion and listing do not work on glob-patterns (see
821 .Sx Filename substitution ) ,
826 editor commands perform
827 equivalent functions for glob-patterns.
828 .Ss Spelling correction (+)
829 The shell can sometimes correct the spelling of filenames, commands and
830 variable names as well as completing and listing them.
832 Individual words can be spelling-corrected with the
834 editor command (usually bound to M-s and M-S)
835 and the entire input buffer with
837 (usually bound to M-$).
840 shell variable can be set to
842 to correct the command name or
844 to correct the entire line each time return is typed, and
846 can be set to correct the word to be completed
847 before each completion attempt.
849 When spelling correction is invoked in any of these ways and
850 the shell thinks that any part of the command line is misspelled,
851 it prompts with the corrected line:
852 .Bd -literal -offset indent
855 CORRECT>ls /usr/bin (y|n|e|a)?
860 or space to execute the corrected line,
862 to leave the uncorrected command in the input buffer,
864 to abort the command as if
867 anything else to execute the original line unchanged.
869 Spelling correction recognizes user-defined completions (see the
872 If an input word in a position for
873 which a completion is defined resembles a word in the completion list,
874 spelling correction registers a misspelling and suggests the latter
875 word as a correction.
876 However, if the input word does not match any of
877 the possible completions for that position, spelling correction does
878 not register a misspelling.
880 Like completion, spelling correction works anywhere in the line,
881 pushing the rest of the line to the right and possibly leaving
882 extra characters to the right of the cursor.
883 .Ss Editor commands (+)
885 lists key bindings and
887 lists and briefly describes editor commands.
888 Only new or especially interesting editor commands are described here.
893 for descriptions of each editor's key bindings.
895 The character or characters to which each command is bound by default is
896 given in parentheses.
898 means a control character and
900 a meta character, typed as
902 on terminals without a meta key.
903 Case counts, but commands that are bound
904 to letters by default are bound to both lower- and uppercase letters for
906 .Bl -tag -width indent
907 .It Ic backward-char Ar (^B, left)
908 Move back a character.
909 Cursor behavior modified by
911 .It Ic backward-delete-word Ar (M-^H, M-^?)
912 Cut from beginning of current word to cursor \- saved in cut buffer.
913 Word boundary behavior modified by
915 .It Ic backward-word Ar (M-b, M-B)
916 Move to beginning of current word.
917 Word boundary and cursor behavior modified by
919 .It Ic beginning-of-line Ar (^A, home)
920 Move to beginning of line.
921 Cursor behavior modified by
923 .It Ic capitalize-word Ar (M-c, M-C)
924 Capitalize the characters from cursor to end of current word.
925 Word boundary behavior modified by
927 .It Ic complete-word Ar (tab)
928 Completes a word as described under
929 .Sx Completion and listing
930 .It Ic complete-word-back Ar (not bound)
932 .Ic complete-word-fwd ,
933 but steps up from the end of the list.
934 .It Ic complete-word-fwd Ar (not bound)
935 Replaces the current word with the first word in the list of possible
937 May be repeated to step down through the list.
938 At the end of the list, beeps and reverts to the incomplete word.
939 .It Ic complete-word-raw Ar (^X-tab)
942 but ignores user-defined completions.
943 .It Ic copy-prev-word Ar (M-^_)
944 Copies the previous word in the current line into the input buffer.
947 Word boundary behavior modified by
949 .It Ic dabbrev-expand Ar (M-/)
950 Expands the current word to the most recent preceding one for which
951 the current is a leading substring, wrapping around the history list
955 without any intervening typing
956 changes to the next previous word etc., skipping identical matches
958 .Ic history-search-backward
960 .It Ic delete-char Ar (not bound)
961 Deletes the character under the cursor.
963 .Ic delete-char-or-list-or-eof
964 Cursor behavior modified by
966 .It Ic delete-char-or-eof Ar (not bound)
969 if there is a character under the cursor or
973 .Ic delete-char-or-list-or-eof
974 Cursor behavior modified by
976 .It Ic delete-char-or-list Ar (not bound)
979 if there is a character under the cursor
982 at the end of the line.
984 .Ic delete-char-or-list-or-eof
985 .It Ic delete-char-or-list-or-eof Ar (^D)
988 if there is a character under the cursor,
990 at the end of the line or
993 See also those three commands, each of which does only a single action, and
994 .Ic delete-char-or-eof ,
995 .Ic delete-char-or-list
998 each of which does a different two out of the three.
999 .It Ic delete-word Ar (M-d, M-D)
1000 Cut from cursor to end of current word \- save in cut buffer.
1001 Word boundary behavior modified by
1003 .It Ic down-history Ar (down-arrow, ^N)
1006 but steps down, stopping at the original input line.
1007 .It Ic downcase-word Ar (M-l, M-L)
1008 Lowercase the characters from cursor to end of current word.
1009 Word boundary behavior modified by
1011 .It Ic end-of-file Ar (not bound)
1012 Signals an end of file, causing the shell to exit unless the
1014 shell variable (q.v.) is set to prevent this.
1016 .Ic delete-char-or-list-or-eof
1017 .It Ic end-of-line Ar (^E, end)
1018 Move cursor to end of line.
1019 Cursor behavior modified by
1021 .It Ic expand-history Ar (M-space)
1022 Expands history substitutions in the current word.
1024 .Sx History substitution
1027 .Ic toggle-literal-history
1031 .It Ic expand-glob Ar (^X-*)
1032 Expands the glob-pattern to the left of the cursor.
1034 .Sx Filename substitution
1035 .It Ic expand-line Ar (not bound)
1037 .Ic expand-history ,
1038 but expands history substitutions in each word in the input buffer.
1039 .It Ic expand-variables Ar (^X-$)
1040 Expands the variable to the left of the cursor.
1042 .Sx Variable substitution
1043 .It Ic forward-char Ar (^F, right)
1044 Move forward one character.
1045 Cursor behavior modified by
1047 .It Ic forward-word Ar (M-f, M-F)
1048 Move forward to end of current word.
1049 Word boundary and cursor behavior modified by
1051 .It Ic history-search-backward Ar (M-p, M-P)
1052 Searches backwards through the history list for a command beginning with
1053 the current contents of the input buffer up to the cursor and copies it
1054 into the input buffer.
1055 The search string may be a glob-pattern (see
1056 .Sx Filename substitution )
1066 will proceed from the
1067 appropriate point in the history list.
1070 .Ic history-search-forward
1073 .It Ic history-search-forward Ar (M-n, M-N)
1075 .Ic history-search-backward ,
1076 but searches forward.
1077 .It Ic i-search-back Ar (not bound)
1078 Searches backward like
1079 .Ic history-search-backward ,
1080 copies the first match
1081 into the input buffer with the cursor positioned at the end of the pattern,
1084 and the first match.
1085 Additional characters may be
1086 typed to extend the search,
1088 may be typed to continue
1089 searching with the same pattern, wrapping around the history list if
1093 single character for this to work) or one of the following special characters
1097 Appends the rest of the word under the cursor to the search pattern.
1098 delete (or any character bound to
1099 .Ic backward-delete-char )
1100 Undoes the effect of the last character typed and deletes a character
1101 from the search pattern if appropriate.
1103 If the previous search was successful, aborts the entire search.
1104 If not, goes back to the last successful search.
1106 Ends the search, leaving the current line in the input buffer.
1108 Any other character not bound to
1109 .Ic self-insert-command
1111 search, leaving the current line in the input buffer, and
1112 is then interpreted as normal input.
1113 In particular, a carriage return
1114 causes the current line to be executed.
1118 .Ic history-search-backward
1119 Word boundary behavior modified by
1121 .It Ic i-search-fwd Ar (not bound)
1124 but searches forward.
1125 Word boundary behavior modified by
1127 .It Ic insert-last-word Ar (M-_)
1128 Inserts the last word of the previous input line
1130 into the input buffer.
1133 .It Ic list-choices Ar (M-^D)
1134 Lists completion possibilities as described under
1135 .Sx Completion and listing
1137 .Ic delete-char-or-list-or-eof
1139 .Ic list-choices-raw
1140 .It Ic list-choices-raw Ar (^X-^D)
1143 but ignores user-defined completions.
1144 .It Ic list-glob Ar (^X-g, ^X-G)
1147 builtin) matches to the glob-pattern
1149 .Sx Filename substitution )
1150 to the left of the cursor.
1151 .It Ic list-or-eof Ar (not bound)
1158 .Ic delete-char-or-list-or-eof
1159 .It Ic magic-space Ar (not bound)
1160 Expands history substitutions in the current line,
1162 .Ic expand-history ,
1163 and inserts a space.
1165 is designed to be bound to the space bar,
1166 but is not bound by default.
1167 .It Ic normalize-command Ar (^X-?)
1168 Searches for the current word in PATH and, if it is found, replaces it with
1169 the full path to the executable.
1170 Special characters are quoted.
1172 expanded and quoted but commands within aliases are not.
1174 useful with commands that take commands as arguments, e.g.,
1178 .It Ic normalize-path Ar (^X-n, ^X-N)
1179 Expands the current word as described under the
1185 .It Ic overwrite-mode Ar (unbound)
1186 Toggles between input and overwrite modes.
1187 .It Ic run-fg-editor Ar (M-^Z)
1188 Saves the current input line and
1189 looks for a stopped job where the file name portion of its first word
1195 is not set, then the file name portion of the
1197 environment variable
1202 environment variable
1206 If such a job is found, it is restarted as if
1210 This is used to toggle back and forth between an editor and
1212 Some people bind this command to
1215 can do this even more easily.
1216 .It Ic run-help Ar (M-h, M-H)
1217 Searches for documentation on the current command, using the same notion of
1219 as the completion routines, and prints it.
1223 is designed for short help files.
1224 If the special alias
1226 is defined, it is run with the
1227 command name as a sole argument.
1229 documentation should be in a file named
1236 which should be in one
1237 of the directories listed in the
1239 environment variable.
1240 If there is more than one help file only the first is printed.
1241 .It Ic self-insert-command Ar (text characters)
1242 In insert mode (the default), inserts the typed character into the input line after the character under the cursor.
1243 In overwrite mode, replaces the character under the cursor with the typed character.
1244 The input mode is normally preserved between lines, but the
1246 shell variable can be set to
1251 editor in that mode at the beginning of each line.
1254 .It Ic sequence-lead-in Ar (arrow prefix, meta prefix, ^X)
1255 Indicates that the following characters are part of a
1257 Binding a command to a multi-key sequence really creates
1258 two bindings: the first character to
1259 .Ic sequence-lead-in
1261 whole sequence to the command.
1262 All sequences beginning with a character
1264 .Ic sequence-lead-in
1265 are effectively bound to
1267 unless bound to another command.
1268 .It Ic spell-line Ar (M-$)
1269 Attempts to correct the spelling of each word in the input buffer, like
1271 but ignores words whose first character is one of
1282 to avoid problems with switches, substitutions and the like.
1284 .Sx Spelling correction
1285 .It Ic spell-word Ar (M-s, M-S)
1286 Attempts to correct the spelling of the current word as described under
1287 .Sx Spelling correction
1288 Checks each component of a word which appears to be a pathname.
1289 .It Ic toggle-literal-history Ar (M-r, M-R)
1292 history substitutions in the input buffer.
1298 .It Ic undefined-key Ar (any unbound key)
1300 .It Ic up-history Ar (up-arrow, ^P)
1301 Copies the previous entry in the history list into the input buffer.
1304 is set, uses the literal form of the entry.
1305 May be repeated to step up through the history list, stopping at the top.
1306 .It Ic upcase-word Ar (M-u, M-U)
1307 Uppercase the characters from cursor to end of current word.
1308 Word boundary behavior modified by
1310 .It Ic vi-beginning-of-next-word Ar (not bound)
1311 Vi goto the beginning of next word.
1312 Word boundary and cursor behavior modified by
1314 .It Ic vi-eword Ar (not bound)
1315 Vi move to the end of the current word.
1316 Word boundary behavior modified by
1318 .It Ic vi-search-back Ar (?)
1321 for a search string (which may be a glob-pattern, as with
1322 .Ic history-search-backward ),
1323 searches for it and copies it into the input buffer.
1324 The bell rings if no match is found.
1325 Hitting return ends the search and leaves the last match in the input
1327 Hitting escape ends the search and executes the match.
1330 .It Ic vi-search-fwd Ar (/)
1332 .Ic vi-search-back ,
1333 but searches forward.
1334 .It Ic which-command Ar (M-?)
1337 (see the description of the builtin command) on the
1338 first word of the input buffer.
1339 .It Ic yank-pop Ar (M-y)
1340 When executed immediately after a
1344 replaces the yanked string with the next previous string from the
1345 killring. This also has the effect of rotating the killring, such that
1346 this string will be considered the most recently killed by a later
1350 will cycle through the
1351 killring any number of times.
1353 .Ss Lexical structure
1354 The shell splits input lines into words at blanks and tabs.
1365 and the doubled characters
1371 are always separate words, whether or not they are
1372 surrounded by whitespace.
1374 When the shell's input is not a terminal, the character
1380 and the rest of the input line on which it appears is
1381 discarded before further parsing.
1383 A special character (including a blank or tab) may be prevented from having
1384 its special meaning, and possibly made part of another word, by preceding it
1387 or enclosing it in single
1395 When not otherwise quoted a newline preceded by a
1397 is equivalent to a blank, but inside quotes this sequence results in a
1403 .Sx History substitution
1404 can be prevented by enclosing the strings (or parts of strings)
1405 in which they appear with single quotes or by quoting the crucial character(s)
1411 .Sx Variable substitution
1413 .Sx Command substitution
1417 .Sx ( Alias substitution
1418 is no exception: quoting in any way any
1419 character of a word for which an
1421 has been defined prevents
1422 substitution of the alias.
1423 The usual way of quoting an alias is to precede it
1425 .Sx History substitution
1427 backslashes but not by single quotes.
1428 Strings quoted with double or backward
1430 .Sx Variable substitution
1432 .Sx Command substitution ,
1433 but other substitutions are prevented.
1435 Text inside single or double quotes becomes a single word (or part of one).
1436 Metacharacters in these strings, including blanks and tabs, do not form
1438 Only in one special case (see
1439 .Sx Command substitution
1440 below) can a double-quoted string yield parts of more than one word;
1441 single-quoted strings never do.
1442 Backward quotes are special: they signal
1443 .Sx Command substitution
1444 (q.v.), which may result in more than one word.
1446 Quoting complex strings, particularly strings which themselves contain quoting
1447 characters, can be confusing.
1448 Remember that quotes need not be used as they are
1450 It may be easier to quote not an entire string, but only
1451 those parts of the string which need quoting, using different types of quoting
1452 to do so if appropriate.
1456 shell variable (q.v.) can be set to make backslashes
1462 (+) This may make complex quoting tasks
1463 easier, but it can cause syntax errors in
1467 We now describe the various transformations the shell performs on the input in
1468 the order in which they occur.
1469 We note in passing the data structures involved
1470 and the commands and variables which affect them.
1471 Remember that substitutions
1472 can be prevented by quoting as described under
1473 .Sx Lexical structure .
1474 .Ss History substitution
1477 input from the terminal is saved in the history list.
1478 The previous command is always saved, and the
1481 variable can be set to a number to save that many commands.
1484 shell variable can be set to not save duplicate events or consecutive duplicate
1487 Saved commands are numbered sequentially from 1 and stamped with the time.
1488 It is not usually necessary to use event numbers, but the current event number
1489 can be made part of the prompt by placing an
1495 The shell actually saves history in expanded and literal (unexpanded) forms.
1498 shell variable is set, commands that display and store
1499 history use the literal form.
1503 builtin command can print, store in a file, restore
1504 and clear the history list at any time,
1509 shell variables can be set to
1510 store the history list automatically on logout and restore it on login.
1512 History substitutions introduce words from the history list into the input
1513 stream, making it easy to repeat commands, repeat arguments of a previous
1514 command in the current command, or fix spelling mistakes in the previous
1515 command with little typing and a high degree of confidence.
1517 History substitutions begin with the character
1519 They may begin anywhere in
1520 the input stream, but they do not nest.
1523 may be preceded by a
1526 prevent its special meaning; for convenience, a
1528 is passed unchanged when it
1529 is followed by a blank, tab, newline,
1533 History substitutions also
1534 occur when an input line begins with
1536 This special abbreviation will be
1538 The characters used to signal history substitution
1542 can be changed by setting the
1546 line which contains a history substitution is printed before it is executed.
1548 A history substitution may have an
1549 .Sq event specification ,
1550 which indicates the event from which words are to be taken, a
1551 .Sq word designator ,
1552 which selects particular words from the chosen event, and/or a
1554 which manipulates the selected words.
1556 An event specification can be
1558 .Bl -tag -width XXXX -offset indent -compact
1560 A number, referring to a particular event
1562 An offset, referring to the event
1564 before the current event
1567 This should be used carefully in
1569 where there is no check for recursion.
1571 allows 10 levels of recursion.
1574 The previous event (equivalent to
1577 The most recent event whose first word begins with the string
1580 The most recent event which contains the string
1584 can be omitted if it is immediately followed by a newline.
1587 For example, consider this bit of someone's history list:
1588 .Bd -literal -offset indent
1589 9 8:30 nroff \-man wumpus.man
1590 10 8:31 cp wumpus.man wumpus.man.old
1591 11 8:36 vi wumpus.man
1592 12 8:37 diff wumpus.man.old wumpus.man
1595 The commands are shown with their event numbers and time stamps.
1596 The current event, which we haven't typed in yet, is event 13.
1602 refers to the previous event, 12.
1610 is described below).
1612 refers to event 9, which begins with
1615 also refers to event 12, which contains
1617 Without word designators or modifiers history references simply expand to the
1618 entire event, so we might type
1620 to redo the copy command or
1624 output scrolled off the top of the screen.
1626 History references may be insulated from the surrounding text with braces if
1630 would look for a command beginning with
1632 and, in this example, not find one, but
1636 .Sq vi wumpus.mandoc
1637 Even in braces, history substitutions do not nest.
1641 expands, for example,
1648 expands it to the last event beginning
1651 only completely numeric arguments are treated as event numbers.
1652 This makes it possible to recall events beginning with numbers.
1660 To select words from an event we can follow the event specification by a
1662 and a designator for the desired words.
1663 The words of an input line are
1664 numbered from 0, the first (usually command) word being 0, the second word
1665 (first argument) being 1, etc.
1666 The basic word designators are:
1667 .Bl -tag -width XXXX -offset indent -compact
1669 The first (command) word
1675 The first argument, equivalent to
1680 The word matched by an ?
1691 but returns nothing if the event contains only 1 word
1698 but omitting the last word
1702 Selected words are inserted into the command line separated by single blanks.
1705 command in the previous example might have been
1707 .Sq diff !!:1.old !!:1
1710 to select the first argument
1711 from the previous event) or
1712 .Sq diff !\-2:2 !\-2:1
1713 to select and swap the
1717 If we didn't care about the order of the
1718 `diff' we might have said
1724 command might have been written
1725 .Sq cp wumpus.man !#:1.old
1728 to refer to the current event.
1729 `!n:\- hurkle.man' would reuse the first two words from the
1733 .Sq nroff \-man hurkle.man
1737 separating the event specification from the word designator can be
1738 omitted if the argument selector begins with a
1747 command might have been
1748 .Sq diff !!^.old !!^
1751 .Sq diff !!$.old !!$
1757 an argument selector beginning with
1759 will be interpreted as an event
1762 A history reference may have a word designator but no event specification.
1763 It then references the previous command.
1766 example, we could have said simply `diff
1767 !^.old !^' or, to get the arguments in the opposite order, just
1770 The word or words in a history reference can be edited, or
1773 by following it with one or more modifiers, each preceded by a
1776 .Bl -tag -width XXXXXX -offset indent -compact
1778 Remove a trailing pathname component, leaving the head.
1780 Remove all leading pathname components, leaving the tail.
1782 Remove a filename extension
1784 leaving the root name.
1786 Remove all but the extension.
1788 Uppercase the first lowercase letter.
1790 Lowercase the first uppercase letter.
1797 is simply a string like
1799 , not a regular expression as in
1803 Any character may be used as the delimiter in place of
1807 can be used to quote the delimiter inside
1826 from a previous substitution or the
1828 from a previous search or event number in event specification is used.
1829 The trailing delimiter may be omitted if it is immediately followed by a
1832 Repeat the previous substitution.
1834 Apply the following modifier once to each word.
1836 Apply the following modifier as many times as possible to a single word.
1840 can be used together to apply a modifier globally.
1843 modifier, only the patterns contained in the original word are
1844 substituted, not patterns that contain any substitution result.
1846 Print the new command line but do not execute it.
1848 Quote the substituted words, preventing further substitutions.
1852 but break into words at blanks, tabs and newlines.
1855 Modifiers are applied to only the first modifiable word (unless
1858 It is an error for no word to be modifiable.
1862 command might have been written as `diff wumpus.man.old
1867 from the first argument on the same line
1870 .Sq echo hello out there
1876 to say it out loud, or
1880 .Sq mail \-s "I forgot my password" rot
1884 correct the spelling of
1887 .Sx Spelling correction
1889 different approach).
1891 There is a special abbreviation for substitutions.
1893 when it is the first character on an input line, is equivalent to
1895 Thus we might have said
1897 to make the spelling correction in the
1899 This is the only history substitution which does not explicitly begin with
1904 as such, only one modifier may be applied to each history
1905 or variable expansion.
1908 more than one may be used, for example
1909 .Bd -literal -offset indent
1910 % mv wumpus.man /usr/man/man1/wumpus.1
1919 A substitution followed by a
1920 colon may need to be insulated from it with braces:
1921 .Bd -literal -offset indent
1922 > mv a.out /usr/games/wumpus
1923 > setenv PATH !$:h:$PATH
1925 > setenv PATH !{\-2$:h}:$PATH
1926 setenv PATH /usr/games:/bin:/usr/bin:.
1929 The first attempt would succeed in
1935 expects another modifier after the second colon
1939 Finally, history can be accessed through the editor as well as through
1940 the substitutions just described.
1945 .Ic history-search-backward
1956 .Ic insert-last-word
1957 editor commands search for
1958 events in the history list and copy them into the input buffer.
1960 .Ic toggle-literal-history
1961 editor command switches between the
1962 expanded and literal forms of history lines in the input buffer.
1966 expand history substitutions
1967 in the current word and in the entire input buffer respectively.
1968 .Ss Alias substitution
1969 The shell maintains a list of aliases which can be set, unset and printed by
1975 After a command line is parsed
1976 into simple commands (see
1978 the first word of each command,
1979 left-to-right, is checked to see if it has an alias.
1980 If so, the first word is
1981 replaced by the alias.
1982 If the alias contains a history reference, it undergoes
1983 .Va History substitution
1984 (q.v.) as though the original command were the
1985 previous input line.
1986 If the alias does not contain a history reference, the
1987 argument list is left untouched.
1989 Thus if the alias for
1996 \-l /usr', the argument list here being undisturbed.
2000 .Sq grep !/etc/passwd
2003 would become `grep bill
2005 Aliases can be used to introduce parser metasyntax.
2009 pr \e!* | lpr'' defines a
2013 (1)s its arguments to the line printer.
2015 Alias substitution is repeated until the first word of the command has no
2017 If an alias substitution does not change the first word (as in the
2018 previous example) it is flagged to prevent a loop.
2019 Other loops are detected and
2022 Some aliases are referred to by the shell; see
2024 .Sx Variable substitution
2025 The shell maintains a list of variables, each of which has as value a list of
2027 The values of shell variables can be displayed and changed with the
2032 The system maintains its own list of
2035 These can be displayed and changed with
2042 (+) Variables may be made read-only with
2045 Read-only variables may not be modified or unset;
2046 attempting to do so will cause an error.
2047 Once made read-only, a variable cannot be made writable,
2050 should be used with caution.
2051 Environment variables cannot be made read-only.
2053 Some variables are set by the shell or referred to by it.
2056 variable is an image of the shell's argument
2057 list, and words of this variable's value are referred to in special ways.
2058 Some of the variables referred to by the shell are toggles;
2059 the shell does not care what their value is, only whether they are set or not.
2062 variable is a toggle which causes command
2065 .Fl v\fR command line option sets this variable.
2066 .Va Special shell variables
2067 lists all variables which are referred to by the shell.
2069 Other operations treat variables numerically.
2072 command permits numeric
2073 calculations to be performed and the result assigned to a variable.
2075 values are, however, always represented as (zero or more) strings.
2077 purposes of numeric operations, the null string is considered to be zero, and
2078 the second and subsequent words of multi-word values are ignored.
2080 After the input line is aliased and parsed, and before each command is
2081 executed, variable substitution is performed keyed by
2085 expansion can be prevented by preceding the
2101 are interpreted later (see
2102 .Sx Command substitution
2105 substitution does not occur there until later,
2109 is passed unchanged if followed by a blank, tab, or
2112 Input/output redirections are recognized before variable expansion, and are
2113 variable expanded separately.
2114 Otherwise, the command name and entire argument
2115 list are expanded together.
2116 It is thus possible for the first (command) word
2117 (to this point) to generate more than one word, the first of which becomes the
2118 command name, and the rest of which become arguments.
2124 modifier the results of variable
2125 substitution may eventually be command and filename substituted.
2129 variable whose value consists of multiple words expands to a (portion of a)
2130 single word, with the words of the variable's value separated by blanks.
2134 modifier is applied to a substitution the variable will expand to
2135 multiple words with each word separated by a blank and quoted to prevent later
2136 command or filename substitution.
2138 The following metasequences are provided for introducing variable values into
2140 Except as noted, it is an error to reference a variable which
2143 .Bl -tag -width XXXXXXXXXX -offset indent -compact
2147 Substitutes the words of the value of variable
2153 from following characters which would
2154 otherwise be part of it.
2155 Shell variables have names consisting of
2156 letters and digits starting with a letter.
2157 The underscore character is
2158 considered a letter.
2161 is not a shell variable, but is set in the
2162 environment, then that value is returned (but some of the other forms
2163 given below are not available in this case).
2164 .It Ar $name[selector]
2165 .It Ar ${name[selector]}
2166 Substitutes only the selected words from the value of
2172 substitution and may consist of
2173 a single number or two numbers separated by a
2175 The first word of a variable's value is numbered
2177 If the first number of a range is omitted it defaults to
2179 If the last member of a range is omitted it defaults to
2186 It is not an error for a range to be empty if the
2187 second argument is omitted or in range.
2189 Substitutes the name of the file from which command input
2191 An error occurs if the name is not known.
2199 which is equivalent to
2205 modifiers described under
2206 .Sx History substitution ,
2209 can be applied to the substitutions above.
2210 More than one may be used.
2212 Braces may be needed to insulate a variable substitution from a literal colon
2214 .Sx History substitution
2215 (q.v.); any modifiers must appear
2218 The following substitutions can not be modified with
2222 .Bl -tag -width XXXXXXXX -offset indent -compact
2225 Substitutes the string
2235 if the current input filename is known,
2240 in interactive shells.
2244 Substitutes the number of words in
2255 Substitutes the number of characters in
2263 Substitutes the number of characters in
2271 Substitutes the (decimal) process number of the (parent) shell.
2273 Substitutes the (decimal) process number of the last
2274 background process started by this shell.
2277 Substitutes the command line of the last command executed.
2280 Substitutes a line from the standard input, with no further interpretation
2282 It can be used to read from the keyboard in a shell script.
2285 always quotes $<, as if it were equivalent to
2291 is waiting for a line to be
2292 typed the user may type an interrupt to interrupt the sequence into
2293 which the line is to be substituted, but
2295 does not allow this.
2299 .Va expand-variables
2302 can be used to interactively expand individual variables.
2303 .Ss "Command, filename and directory stack substitution"
2304 The remaining substitutions are applied selectively to the arguments
2305 of builtin commands.
2306 This means that portions of expressions which are not evaluated are
2307 not subjected to these expansions.
2308 For commands which are not internal to the
2309 shell, the command name is substituted separately from the argument list.
2310 This occurs very late, after input-output redirection is performed, andk
2311 in a child of the main shell.
2312 .Ss "Command substitution"
2313 Command substitution is indicated by a command enclosed in
2316 from such a command is broken into separate words at blanks, tabs and newlines,
2317 and null words are discarded.
2318 The output is variable and command substituted
2319 and put in place of the original string.
2321 Command substitutions inside double
2324 retain blanks and tabs; only newlines force new words.
2326 final newline does not force a new word in any case.
2327 It is thus possible for a
2328 command substitution to yield only part of a word, even if the command outputs
2331 By default, the shell since version 6.12 replaces all newline and carriage
2332 return characters in the command by spaces.
2333 If this is switched off by
2336 newlines separate commands as usual.
2337 .Ss "Filename substitution"
2338 If a word contains any of the characters
2347 it is a candidate for filename substitution, also known as
2349 This word is then regarded as a pattern
2350 .Dq ( glob-pattern ) ,
2352 replaced with an alphabetically sorted list of file names which match the
2355 In matching filenames, the character
2357 at the beginning of a filename or
2358 immediately following a
2360 as well as the character
2363 explicitly (unless either
2367 or both are set(+)).
2370 matches any string of characters,
2371 including the null string.
2374 matches any single character.
2377 matches any one of the characters enclosed.
2381 characters separated by
2383 matches any character lexically between the two.
2385 (+) Some glob-patterns can be negated:
2388 matches any single character
2391 characters and/or ranges of characters in the braces.
2393 An entire glob-pattern can also be negated with
2395 .Bd -literal -offset indent
2397 bang crash crunch ouch
2402 Glob-patterns which do not use
2410 (below) are not negated correctly.
2416 Left-to-right order is preserved:
2417 .Sq /usr/source/s1/{oldls,ls}.c
2420 .Sq /usr/source/s1/oldls.c /usr/source/s1/ls.c
2421 The results of matches are
2422 sorted separately at a low level to preserve this order:
2425 .Sq ../memo ../box ../mbox
2428 was not sorted with the results of matching
2430 It is not an error when this construct expands to files which do not exist,
2431 but it is possible to get an error from a command to which the expanded list
2433 This construct may be nested.
2434 As a special case the words
2439 are passed undisturbed.
2443 at the beginning of a filename refers to home directories.
2444 Standing alone, i.e.,
2446 it expands to the invoker's home directory as
2447 reflected in the value of the
2451 name consisting of letters, digits and
2453 characters the shell searches for a
2454 user with that name and substitutes their home directory; thus
2465 is followed by a character other than a letter or
2467 or appears elsewhere
2468 than at the beginning of a word, it is left undisturbed.
2470 .Sq setenv MANPATH /usr/man:/usr/local/man:~/lib/man
2472 therefore, do home directory substitution as one might hope.
2474 It is an error for a glob-pattern containing
2483 not to match any files.
2484 However, only one pattern in a list of
2485 glob-patterns must match a file (so that, e.g.,
2488 only if there were no files in the current directory ending in
2495 shell variable is set a pattern (or list
2496 of patterns) which matches nothing is left unchanged rather than causing
2501 shell variable can be set to allow
2506 a file glob pattern that matches any string of characters including
2508 recursively traversing any existing sub-directories.
2511 will list all the .c files in the current directory tree.
2512 If used by itself, it will match zero or more sub-directories
2514 .Sq ls /usr/include/**/time.h
2515 will list any file named
2517 in the /usr/include directory tree;
2518 .Sq ls /usr/include/**time.h
2520 any file in the /usr/include directory tree ending in
2523 .Sq ls /usr/include/**time**.h
2524 will match any .h file with
2527 in a subdirectory name or in the filename itself).
2528 To prevent problems with recursion, the
2530 glob-pattern will not
2531 descend into a symbolic link containing a directory.
2539 shell variable can be set to prevent filename substitution,
2542 editor command, normally bound to
2545 used to interactively expand individual filename substitutions.
2546 .Ss "Directory stack substitution (+)"
2547 The directory stack is a list of directories, numbered from zero, used by the
2552 builtin commands (q.v.).
2554 can print, store in a file, restore and clear the directory stack
2555 at any time, and the
2559 shell variables can be set to
2560 store the directory stack automatically on logout and restore it on login.
2563 shell variable can be examined to see the directory stack and
2564 set to put arbitrary directories into the directory stack.
2568 followed by one or more digits expands to an entry in
2569 the directory stack.
2572 expands to the last directory in
2575 .Bd -literal -offset indent
2592 shell variables and the
2594 editor command apply to directory stack as well as filename substitutions.
2595 .Ss "Other substitutions (+)"
2596 There are several more transformations involving filenames, not strictly
2597 related to the above but mentioned here for completeness.
2599 filename may be expanded to a full path when the
2601 variable (q.v.) is set to
2603 Quoting prevents this expansion, and
2606 editor command does it on demand.
2608 .Va normalize-command
2609 editor command expands commands in PATH into
2610 full paths on demand.
2617 as the old working directory
2618 (equivalent to the shell variable
2620 This is not a substitution at all, but an abbreviation recognized by only
2622 Nonetheless, it too can be prevented by quoting.
2624 The next three sections describe how the shell executes commands and
2625 deals with their input and output.
2626 .Ss "Simple commands, pipelines and sequences"
2627 A simple command is a sequence of words, the first of which specifies the
2628 command to be executed.
2629 A series of simple commands joined by
2633 The output of each command in a pipeline is connected to the
2636 Simple commands and pipelines may be joined into sequences with
2639 be executed sequentially.
2640 Commands and pipelines can also be joined into
2645 indicating, as in the C language, that the second
2646 is to be executed only if the first fails or succeeds respectively.
2648 A simple command, pipeline or sequence may be placed in parentheses,
2650 to form a simple command, which may in turn be a component of a pipeline or
2652 A command, pipeline or sequence can be executed
2653 without waiting for it to terminate by following it with an
2655 .Ss "Builtin and non-builtin command execution"
2656 Builtin commands are executed within the shell.
2657 If any component of a
2658 pipeline except the last is a builtin command, the pipeline is executed
2661 Parenthesized commands are always executed in a subshell.
2662 .Bd -literal -offset indent
2668 directory, leaving you where you were
2669 (printing this after the home directory), while
2670 .Bd -literal -offset indent
2677 Parenthesized commands are most often
2680 from affecting the current shell.
2682 When a command to be executed is found not to be a builtin command the shell
2683 attempts to execute the command via
2685 Each word in the variable
2687 names a directory in which the shell will look for the
2689 If the shell is not given a
2692 hashes the names in these directories into an internal table so that it will
2695 in only a directory where there is a possibility that the
2696 command resides there.
2697 This greatly speeds command location when a large
2698 number of directories are present in the search path. This hashing mechanism is
2701 .Bl -enum -width indent
2703 If hashing is turned explicitly off via
2706 If the shell was given a
2709 For each directory component of
2711 which does not begin with a
2714 If the command contains a
2718 In the above four cases the shell concatenates each component of the path
2719 vector with the given command name to form a path name of a file which it
2720 then attempts to execute it. If execution is successful, the search stops.
2722 If the file has execute permissions but is not an executable to the system
2723 (i.e., it is neither an executable binary nor a script that specifies its
2724 interpreter), then it is assumed to be a file containing shell commands and
2725 a new shell is spawned to read it.
2728 special alias may be set
2729 to specify an interpreter other than the shell itself.
2731 On systems which do not understand the
2733 script interpreter convention
2734 the shell may be compiled to emulate it; see the
2738 If so, the shell checks the first line of the file to
2739 see if it is of the form
2740 .Sq #!interpreter arg ...
2747 file to it on standard input.
2749 The standard input and standard output of a command may be redirected with the
2752 .Bl -tag -width XXXXXX -offset indent -compact
2756 (which is first variable, command and filename
2757 expanded) as the standard input.
2759 Read the shell input up to a line which is identical to
2762 is not subjected to variable, filename or command substitution, and each input
2765 before any substitutions are done on this input
2777 command substitution is performed on the intervening lines, allowing
2785 Commands which are substituted have all blanks, tabs,
2786 and newlines preserved, except for the final newline which is dropped.
2788 resultant text is placed in an anonymous temporary file which is given to the
2789 command as standard input.
2797 is used as standard output.
2798 If the file does not exist
2799 then it is created; if the file exists, it is truncated, its previous contents
2802 If the shell variable
2804 is set, then the file must not exist or be a
2805 character special file (e.g., a terminal or
2807 or an error results.
2808 This helps prevent accidental destruction of files.
2812 can be used to suppress this check.
2818 is allowed on empty files;
2821 is set, an interacive confirmation is presented, rather than an
2826 route the diagnostic output into the specified file as
2827 well as the standard output.
2829 is expanded in the same way as
2831 input filenames are.
2839 , but appends output to the end of
2841 If the shell variable
2843 is set, then it is an error for
2846 to exist, unless one of the
2851 A command receives the environment in which the shell was invoked as modified
2852 by the input-output parameters and the presence of the command in a pipeline.
2853 Thus, unlike some previous shells, commands run from a file of shell commands
2854 have no access to the text of the commands by default; rather they receive the
2855 original standard input of the shell.
2858 mechanism should be used to
2859 present inline data.
2860 This permits shell command scripts to function as
2861 components of pipelines and allows the shell to block read its input.
2863 that the default standard input for a command run detached is
2867 but the original standard input of the shell.
2868 If this is a terminal and if the process attempts to read from the terminal,
2869 then the process will block and the user will be notified (see
2872 Diagnostic output may be directed through a pipe with the standard output.
2878 The shell cannot presently redirect diagnostic output without also redirecting
2879 standard output, but
2880 .Sq \&( command > output-file ) >& error-file
2881 is often an acceptable workaround.
2888 to send output to the terminal.
2890 Having described how the shell accepts, parses and executes
2891 command lines, we now turn to a variety of its useful features.
2893 The shell contains a number of commands which can be used to regulate the
2894 flow of control in command files (shell scripts) and (in limited but
2895 useful ways) from terminal input.
2896 These commands all operate by forcing the
2897 shell to reread or skip in its input and, due to the implementation,
2898 restrict the placement of some of the commands.
2905 statements, as well as the
2909 statement, require that the major
2910 keywords appear in a single simple command on an input line as shown below.
2912 If the shell's input is not seekable, the shell buffers up input whenever
2913 a loop is being read and performs seeks in this internal buffer to
2914 accomplish the rereading implied by the loop.
2915 (To the extent that this allows, backward
2917 s will succeed on non-seekable inputs.)
2925 use expressions with a common syntax.
2926 The expressions can include any
2927 of the operators described in the next three sections.
2930 builtin command (q.v.) has its own separate syntax.
2931 .Ss "Logical, arithmetical and comparison operators"
2932 These operators are similar to those of C and have the same precedence.
2935 .Bl -tag -width XXXXXX -offset indent -compact
2936 .It || && | & == != =~ !~ <= >=
2937 .It < > << >> + \- * / % ! ~ ( )
2940 Here the precedence increases to the right,
2961 groups, at the same level.
2969 their arguments as strings; all others operate on numbers.
2978 except that the right hand side is a
2980 .Sx Filename substitution )
2981 against which the left hand operand is matched.
2982 This reduces the need for use of the
2984 builtin command in shell scripts when all that is really needed is
2988 missing arguments are considered
2990 The results of all expressions are
2991 strings, which represent decimal numbers.
2992 It is important to note that
2993 no two components of an expression can appear in the same word; except
2994 when adjacent to components of expressions which are syntactically
2995 significant to the parser
3003 surrounded by spaces.
3004 .Ss "Command exit status"
3005 Commands can be executed in expressions and their exit status
3006 returned by enclosing them in braces
3008 Remember that the braces should
3009 be separated from the words of the command by spaces.
3011 succeed, returning true, i.e.,
3013 if the command exits with status 0,
3014 otherwise they fail, returning false, i.e.,
3016 If more detailed status
3017 information is required then the command should be executed outside of an
3020 shell variable examined.
3021 .Ss "File inquiry operators"
3022 Some of these operators perform true/false tests on files and related
3024 They are of the form
3030 .Bl -tag -width XXX -offset indent -compact
3038 Executable in the path or shell builtin, e.g.,
3061 Block special file (+)
3063 Character special file (+)
3065 Named pipe (fifo) (+) *
3067 Socket special file (+) *
3069 Set-user-ID bit is set (+)
3071 Set-group-ID bit is set (+)
3073 Sticky bit is set (+)
3075 (which must be a digit) is an open file descriptor
3076 for a terminal device (+)
3078 Has been migrated (Convex only) (+)
3080 Applies subsequent operators in a multiple-operator test to a symbolic link
3081 rather than to the file to which the link points (+) *
3085 is command and filename expanded and then tested to
3086 see if it has the specified relationship to the real user.
3089 does not exist or is inaccessible or, for the operators indicated by
3091 if the specified file type does not exist on the current system,
3092 then all inquiries return false, i.e.,
3095 These operators may be combined for conciseness:
3100 .Sq \&-x file && \&-y file .
3106 for plain executable files, but not for directories.
3109 may be used in a multiple-operator test to apply subsequent operators
3110 to a symbolic link rather than to the file to which the link points.
3113 is true for links owned by the invoking user.
3118 are always true for links and false for
3121 has a different meaning when it is the last operator
3122 in a multiple-operator test; see below.
3124 It is possible but not useful, and sometimes misleading, to combine operators
3127 to be a file with operators which do not
3134 with a non-file operator
3135 can lead to particularly strange results.
3137 Other operators return other information, i.e., not just
3142 They have the same format as before;
3150 Last file access time, as the number of seconds since the epoch
3155 , but in timestamp format, e.g.,
3156 .Sq Fri May 14 16:36:10 1993
3159 Last file modification time
3164 , but in timestamp format
3167 Last inode modification time
3172 , but in timestamp format
3183 ile identifier, in the form
3189 The name of the file pointed to by a symbolic link
3192 Number of (hard) links
3195 Permissions, in octal, without leading zero
3214 is writable by group and other,
3230 Username, or the numeric userid if the username is unknown
3236 Groupname, or the numeric groupid if the groupname is unknown
3243 Only one of these operators may appear in a multiple-operator test, and it
3247 has a different meaning at the end of and
3248 elsewhere in a multiple-operator test.
3251 is a valid return value
3252 for many of these operators, they do not return
3254 when they fail: most
3262 If the shell is compiled with POSIX defined (see the
3265 variable), the result of a file inquiry is based on the permission bits of
3266 the file and not on the result of the
3269 For example, if one tests a file with
3270 .Fl w\fR whose permissions would
3271 ordinarily allow writing but which is on a file system mounted read-only,
3272 the test will succeed in a POSIX shell but fail in a non-POSIX shell.
3274 File inquiry operators can also be evaluated with the
3279 The shell associates a
3283 current jobs, printed by the
3285 command, and assigns them small integer
3287 When a job is started asynchronously with
3289 , the shell prints a
3290 line which looks like
3294 indicating that the job which was started asynchronously was job number 1 and
3295 had one (top-level) process, whose process id was 1234.
3297 If you are running a job and wish to do something else you may hit the suspend
3300 which sends a STOP signal to the current job.
3301 The shell will then normally
3302 indicate that the job has been
3304 and print another prompt.
3307 shell variable is set, all jobs will be listed
3310 builtin command; if it is set to
3313 be in long format, like
3315 You can then manipulate the state of the suspended job.
3316 You can put it in the
3320 command or run some other commands and
3321 eventually bring the job back into the
3330 takes effect immediately and is like an interrupt
3331 in that pending output and unread input are discarded when it is typed.
3334 builtin command causes the shell to wait for all background
3339 key sends a delayed suspend signal, which does not generate a STOP
3340 signal until a program attempts to
3342 (2) it, to the current job.
3343 This can usefully be typed ahead when you have prepared some commands for a
3344 job which you wish to stop after it has read them.
3347 key performs this function in
3352 `^Y' is an editing command.
3355 A job being run in the background stops if it tries to read from the
3357 Background jobs are normally allowed to produce output, but this can
3358 be disabled by giving the command
3360 If you set this tty option,
3361 then background jobs will stop when they try to produce output like they do
3362 when they try to read input.
3364 There are several ways to refer to jobs in the shell.
3367 introduces a job name.
3368 If you wish to refer to job number 1, you can name it
3371 Just naming a job brings it to the foreground; thus
3376 , bringing job 1 back into the foreground.
3379 resumes job 1 in the background, just like
3381 A job can also be named
3382 by an unambiguous prefix of the string typed in to start it:
3385 normally restart a suspended
3387 (1) job, if there were only one suspended
3388 job whose name began with the string
3390 It is also possible to say
3393 ' to specify a job whose text contains
3396 is only one such job.
3398 The shell maintains a notion of the current and previous jobs.
3400 pertaining to jobs, the current job is marked with a
3402 and the previous job
3409 , and (by analogy with the syntax of
3414 all refer to the current job, and
3417 to the previous job.
3419 The job control mechanism requires that the
3425 It is an artifact from a
3427 implementation of the tty
3428 driver which allows generation of interrupt characters from the keyboard to
3435 details on setting options in the new tty driver.
3436 .Ss "Status reporting"
3437 The shell learns immediately whenever a process changes state.
3439 informs you whenever a job becomes blocked so that no further progress is
3440 possible, but only right before it prints a prompt.
3441 This is done so that it
3442 does not otherwise disturb your work.
3443 If, however, you set the shell variable
3445 , the shell will notify you immediately of changes of status in
3447 There is also a shell command
3450 single process so that its status changes will be immediately reported.
3454 marks the current process; simply say
3457 starting a background job to mark it.
3459 When you try to leave the shell while jobs are stopped, you will be
3461 .Sq There are suspended jobs.
3466 If you do this or immediately try to exit again, the shell
3467 will not warn you a second time, and the suspended jobs will be terminated.
3468 .Ss "Automatic, periodic and timed events (+)"
3469 There are various ways to run commands and take other actions automatically
3470 at various times in the
3473 They are summarized here,
3474 and described in detail under the appropriate
3475 .Va Builtin commands
3477 .Va Special shell variables
3483 builtin command puts commands in a scheduled-event list,
3484 to be executed by the shell at a given time.
3500 can be set, respectively, to execute commands when the shell wants
3501 to ring the bell, when the working directory changes, every
3503 minutes, before each prompt, before each command gets executed, after each
3504 command gets executed, and when a job is started or is brought into the
3509 shell variable can be set to log out or lock the shell
3510 after a given number of minutes of inactivity.
3514 shell variable can be set to check for new mail periodically.
3518 shell variable can be set to print the exit status
3519 of commands which exit with a status other than zero.
3523 shell variable can be set to ask the user, when
3526 typed, if that is really what was meant.
3530 shell variable can be set to execute the
3533 command after the completion of any process that takes more than a given
3534 number of CPU seconds.
3540 shell variables can be set to report when
3541 selected users log in or out, and the
3543 builtin command reports
3544 on those users at any time.
3545 .Ss "Native Language System support (+)"
3546 The shell is eight bit clean
3547 (if so compiled; see the
3550 and thus supports character sets needing this capability.
3551 NLS support differs depending on whether or not
3552 the shell was compiled to use the system's NLS (again, see
3555 In either case, 7-bit ASCII is the default character code
3556 (e.g., the classification of which characters are printable) and sorting,
3561 environment variables
3562 causes a check for possible changes in these respects.
3564 When using the system's NLS, the
3566 (3) function is called
3567 to determine appropriate character code/classification and sorting
3568 (e.g., a 'en_CA.UTF-8' would yield "UTF-8" as a character code).
3569 This function typically examines the
3573 environment variables; refer to the system documentation for further details.
3574 When not using the system's NLS, the shell simulates it by assuming that the
3575 ISO 8859-1 character set is used
3576 whenever either of the
3580 variables are set, regardless of
3582 Sorting is not affected for the simulated NLS.
3584 In addition, with both real and simulated NLS, all printable
3585 characters in the range \e200\-\e377, i.e., those that have
3588 bindings, are automatically rebound to
3589 .Va self-insert-command
3590 The corresponding binding for the escape-
3592 sequence, if any, is
3594 These characters are not rebound if the
3596 environment variable
3598 This may be useful for the simulated NLS or a primitive real NLS
3599 which assumes full ISO 8859-1.
3603 range \e240\-\e377 are effectively undone.
3604 Explicitly rebinding the relevant keys with
3606 is of course still possible.
3608 Unknown characters (i.e., those that are neither printable nor control
3609 characters) are printed in the format \ennn.
3610 If the tty is not in 8 bit mode, other 8 bit characters are printed by
3611 converting them to ASCII and using standout mode.
3613 never changes the 7/8 bit mode of the tty and tracks user-initiated
3614 changes of 7/8 bit mode.
3615 NLS users (or, for that matter, those who want to
3616 use a meta key) may need to explicitly set
3617 the tty in 8 bit mode through the appropriate
3620 command in, e.g., the
3623 .Ss "OS variant support (+)"
3624 A number of new builtin commands are provided to support features in
3625 particular operating systems.
3626 All are described in detail in the
3627 .Va Builtin commands
3630 On systems that support TCF (aix-ibm370, aix-ps2),
3634 get and set the system execution path,
3638 get and set the experimental version prefix
3641 migrates processes between sites.
3645 prints the site on which each job is executing.
3649 executes commands of the underlying BS2000/OSD
3654 adds shared libraries to the current environment,
3656 changes the rootnode and
3658 changes the systype.
3662 is equivalent to Mach's
3666 Under Masscomp/RTU and Harris CX/UX,
3674 runs a command under the specified
3679 prints or sets the universe.
3687 environment variables
3688 indicate respectively the vendor, operating system and machine type
3689 (microprocessor class or machine model) of the
3690 system on which the shell thinks it is running.
3691 These are particularly useful when sharing one's home directory between several
3692 types of machines; one can, for example,
3694 set path = (~/bin.$MACHTYPE /usr/ucb /bin /usr/bin .)
3698 and put executables compiled for each machine in the
3699 appropriate directory.
3704 variable indicates what options were chosen when the shell was compiled.
3712 shell variables and the system-dependent locations of
3713 the shell's input files (see
3716 .Ss "Signal handling"
3717 Login shells ignore interrupts when reading the file
3719 The shell ignores quit signals unless started with
3721 Login shells catch the terminate signal, but non-login shells inherit the
3722 terminate behavior from their parents.
3723 Other signals have the values which the shell inherited from its parent.
3725 In shell scripts, the shell's handling of interrupt and terminate signals
3726 can be controlled with
3728 , and its handling of hangups can be
3734 The shell exits on a hangup (see also the
3738 default, the shell's children do too, but the shell does not send them a
3739 hangup when it exits.
3741 arranges for the shell to send a hangup to
3742 a child when it exits, and
3744 sets a child to ignore hangups.
3745 .Ss "Terminal management (+)"
3746 The shell uses three different sets of terminal (
3749 `edit', used when editing,
3751 , used when quoting literal characters,
3754 , used when executing commands.
3755 The shell holds some settings in each mode constant, so commands which leave
3756 the tty in a confused state do not interfere with the shell.
3757 The shell also matches changes in the speed and padding of the tty.
3758 The list of tty modes that are kept constant
3759 can be examined and modified with the
3762 Note that although the editor uses CBREAK mode (or its equivalent),
3763 it takes typed-ahead characters anyway.
3771 commands can be used to
3772 manipulate and debug terminal capabilities from the command line.
3774 On systems that support SIGWINCH or SIGWINDOW, the shell
3775 adapts to window resizing automatically and adjusts the environment
3784 contains li# and co# fields, the shell adjusts
3785 them to reflect the new window size.
3787 The next sections of this manual describe all of the available
3788 .Va Builtin commands
3792 .Va Special shell variables
3793 .Ss "Builtin commands"
3806 Does nothing, successfully.
3810 .B @ \fIname\fB = \fIexpr
3830 The first form prints the values of all shell variables.
3834 The second form assigns the value of
3838 The third form assigns the value of
3853 may contain the operators
3868 then at least that part of
3870 must be placed within
3872 Note that the syntax of
3874 has nothing to do with that described
3878 The fourth and fifth forms increment (`++') or decrement (`\-\-')
3900 must be separated by spaces.
3909 Without arguments, prints all aliases.
3912 , prints the alias for name.
3922 is command and filename substituted.
3933 Shows the amount of dynamic memory acquired, broken down into used and free
3935 With an argument shows the number of free and used blocks in each size
3937 The categories start at size 8 and double at each step.
3939 command's output may vary across system types, because systems other than the VAX
3940 may use a different memory allocator.
3945 Puts the specified jobs (or, without arguments, the current job)
3946 into the background, continuing each if it is stopped.
3948 may be a number, a string,
3988 .\" .B macro can't take too many words, so I used \fB in the previous tags
3989 Without options, the first form lists all bound keys and the editor command to which each is bound,
3990 the second form lists the editor command to which
3993 the third form binds the editor command
4004 Lists all editor commands and a short description of each.
4007 Binds all keys to the standard bindings for the default editor,
4017 (1)\-style bindings.
4024 (1)\-style bindings.
4029 Lists or changes key-bindings in the alternative key map.
4030 This is the key map used in
4037 a control character written ^
4047 a meta character written M-
4052 a function key written F-
4057 or an extended prefix key written X-
4065 is interpreted as a symbolic arrow key name, which may be one of
4084 .Va self-insert-command
4091 is interpreted as a builtin or external command instead of an
4096 is taken as a literal string and treated as terminal input
4103 reinterpreted, and this continues for ten levels of interpretation.
4106 Forces a break from option processing, so the next word is taken as
4108 even if it begins with '\-'.
4110 .Fl u \fR(or any invalid option)
4111 Prints a usage message.
4115 may be a single character or a string.
4116 If a command is bound to a string, the first character of the string is bound to
4117 .Va sequence-lead-in
4118 and the entire string is bound to the command.
4120 Control characters in
4122 can be literal (they can be typed by preceding
4123 them with the editor command
4128 written caret-character style, e.g.,
4132 (caret-question mark).
4136 can contain backslashed
4137 escape sequences (in the style of System V
4168 The ASCII character corresponding to the octal number
4173 `\e' nullifies the special meaning of the following character, if it has
4185 to the BS2000 command interpreter for
4186 execution. Only non-interactive commands can be executed, and it is
4187 not possible to execute any command that would overlay the image
4188 of the current process, like /EXECUTE or /CALL-PROCEDURE. (BS2000 only)
4191 Causes execution to resume after the
4198 The remaining commands on the
4199 current line are executed.
4200 Multi-level breaks are thus
4201 possible by writing them all on one line.
4204 Causes a break from a
4206 , resuming after the
4210 Prints the names of all builtin commands.
4216 Available only if the shell was so compiled;
4221 .B case \fIlabel\fB:
4224 statement as discussed below.
4230 .Fl v\fR] [\I--\fR] [
4235 is given, changes the shell's working directory
4242 variable is not set, in which case a
4249 it is interpreted as the previous working directory
4251 .Va Other substitutions
4256 is not a subdirectory of the current directory
4257 (and does not begin with
4263 ), each component of the variable
4265 is checked to see if it has a subdirectory
4270 is a shell variable whose value
4273 or '.', then this is tried to see if it is a directory, and
4275 .Fl p\fR option is implied.
4279 .Fl p\fR, prints the final directory stack, just like
4284 .Fl v\fR flags have the same effect on
4292 .Fl \-\fR forces a break from option processing so the next word
4293 is taken as the directory
4295 even if it begins with '\-'. (+)
4311 [\fIword\fB/\fIpattern\fB/
4322 Without arguments, lists all completions.
4325 , lists completions for
4331 etc., defines completions.
4335 may be a full command name or a glob-pattern
4337 .Va Filename substitution
4342 completion should be used only when
4347 specifies which word relative to the current word
4348 is to be completed, and may be one of the following:
4354 Current-word completion.
4356 is a glob-pattern which must match the beginning of the current word on
4359 is ignored when completing the current word.
4366 when completing the current word.
4369 Next-word completion.
4371 is a glob-pattern which must match the beginning of the previous word on
4377 , but must match the beginning of the word two before the current word.
4380 Position-dependent completion.
4382 is a numeric range, with the same syntax used to index shell
4383 variables, which must include the current word.
4388 , the list of possible completions, may be one of the following:
4397 Bindings (editor commands)
4400 Commands (builtin or external commands)
4403 External commands which begin with the supplied path prefix
4409 Directories which begin with the supplied path prefix
4412 Environment variables
4418 Filenames which begin with the supplied path prefix
4446 files which begin with the supplied path prefix
4468 Words from the variable
4472 Words from the given list
4475 Words from the output of command
4480 is an optional glob-pattern.
4481 If given, words from only
4488 shell variable is ignored.
4489 The last three types of completion may not have a
4495 as an explanatory message when
4498 editor command is used.
4501 is a single character to be appended to a successful
4503 If null, no character is appended.
4504 If omitted (in which
4505 case the fourth delimiter can also be omitted), a slash is appended to
4506 directories and a space to other words.
4509 invoked from \`...\` version has additional environment
4510 variable set, the variable name is \%
4513 contains (as its name indicates) contents of the current (already
4514 typed in) command line. One can examine and use contents of the
4517 \% variable in her custom script to build more
4518 sophisticated completions (see completion for svn(1) included in
4521 Now for some examples.
4522 Some commands take only directories as arguments,
4523 so there's no point completing plain files.
4525 > complete cd 'p/1/d/'
4527 completes only the first word following
4529 (`p/1') with a directory.
4531 -type completion can also be used to narrow down command completion:
4537 > complete \-co* 'p/0/(compress)/'
4543 This completion completes commands (words in position 0,
4556 indicates that this completion is to be used with only
4559 > complete find 'n/\-user/u/'
4567 immediately following
4569 is completed from the list of users.
4571 > complete cc 'c/\-I/d/'
4581 is completed as a directory.
4582 `\-I' is not taken as part of the
4583 directory because we used lowercase
4588 s are useful with different commands.
4590 > complete alias 'p/1/a/'
4592 > complete man 'p/*/c/'
4594 > complete set 'p/1/s/'
4596 > complete true 'p/1/x:Truth has no options./'
4598 These complete words following
4605 with shell variables.
4606 `true' doesn't have any options, so
4608 does nothing when completion
4609 is attempted and prints
4610 .Sq Truth has no options.
4611 when completion choices are listed.
4615 example, and several other examples below, could
4616 just as well have used 'c/*' or 'n/*' as 'p/*'.
4618 Words can be completed from a variable evaluated at completion time,
4620 > complete ftp 'p/1/$hostnames/'
4622 > set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu)
4626 rtfm.mit.edu tesla.ee.cornell.edu
4630 > set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net)
4634 rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net
4636 or from a command run at completion time:
4638 > complete kill 'p/*/\`ps | awk \e{print\e \e$1\e}\`/'
4642 23113 23377 23380 23406 23429 23529 23530 PID
4646 command does not itself quote its arguments,
4647 so the braces, space and
4651 must be quoted explicitly.
4653 One command can have multiple completions:
4655 > complete dbx 'p/2/(core)/' 'p/*/c/'
4657 completes the second argument to
4662 arguments with commands.
4663 Note that the positional completion is specified
4664 before the next-word completion.
4665 Because completions are evaluated from left to right, if
4666 the next-word completion were specified first it would always match
4667 and the positional completion would never be executed.
4669 common mistake when defining a completion.
4673 pattern is useful when a command takes files with only
4674 particular forms as arguments.
4677 > complete cc 'p/*/f:*.[cao]/'
4681 arguments to files ending in only
4688 can also exclude files, using negation of a glob-pattern as
4690 .Va Filename substitution
4693 > complete rm 'p/*/f:^*.{c,h,cc,C,tex,1,man,l,y}/'
4695 to exclude precious source code from
4699 could still type excluded names manually or override the completion
4701 .Va complete-word-raw
4703 .Va list-choices-raw
4704 editor commands (q.v.).
4724 respectively, but they use the
4726 argument in a different way: to
4727 restrict completion to files beginning with a particular path prefix.
4729 example, the Elm mail program uses
4731 as an abbreviation for one's mail
4735 > complete elm c@=@F:$HOME/Mail/@
4745 to avoid confusion with the
4747 argument, and we used
4750 because home directory substitution works at only the
4751 beginning of a word.
4754 is used to add a nonstandard suffix
4757 for directories) to completed words.
4759 > complete finger 'c/*@/$hostnames/' 'p/1/u/@'
4761 completes arguments to
4763 from the list of users, appends an
4766 and then completes after the
4772 again the order in which the completions are specified.
4774 Finally, here's a complex example for inspiration:
4778 \&'n/\-name/f/' 'n/\-newer/f/' 'n/\-{,n}cpio/f/' \e
4780 \&\'n/\-exec/c/' 'n/\-ok/c/' 'n/\-user/u/' \e
4782 \&'n/\-group/g/' 'n/\-fstype/(nfs 4.2)/' \e
4784 \&'n/\-type/(b c d f l p s)/' \e
4786 \'c/\-/(name newer cpio ncpio exec ok user \e
4788 group fstype type atime ctime depth inum \e
4790 ls mtime nogroup nouser perm print prune \e
4796 This completes words following
4804 (note the pattern which matches both) to files,
4809 to commands, words following
4813 to users and groups respectively
4820 It also completes the switches themselves from the given list
4824 and completes anything not otherwise completed to a directory.
4827 Remember that programmed completions are ignored if the word being completed
4828 is a tilde substitution (beginning with
4830 ) or a variable (beginning with
4839 Continues execution of the nearest enclosing
4843 The rest of the commands on the current line are executed.
4846 Labels the default case in a
4849 It should come after all
4865 The first form prints the directory stack.
4866 The top of the stack is at the
4867 left and the first directory in the stack is the current directory.
4873 in the output is expanded explicitly
4876 or the pathname of the home directory for user \fIname\fP.
4879 .Fl n\fR, entries are wrapped before they reach the edge of the screen.
4882 .Fl v\fR, entries are printed one per line, preceded by their stack positions.
4887 .Fl v\fR takes precedence.
4888 .Fl p\fR is accepted but does nothing.
4893 .Fl S\fR, the second form saves the directory stack to
4901 .Fl L\fR, the shell sources
4903 , which is presumably
4904 a directory stack file saved by the
4905 .Fl S\fR option or the
4918 Note that login shells do the equivalent of
4928 is normally sourced before
4937 The last form clears the directory stack.
4946 to the shell's standard
4947 output, separated by spaces and terminated with a newline.
4950 shell variable may be set to emulate (or not) the flags and escape
4951 sequences of the BSD and/or System V versions of
4961 Exercises the terminal capabilities (see
4965 For example, 'echotc home' sends the cursor to the home position,
4966 \&'echotc cm 3 10' sends it to column 3 and row 10, and
4967 \&'echotc ts 0; echo "This is a test."; echotc fs' prints "This is a test."
4973 is 'baud', 'cols', 'lines', 'meta' or 'tabs', prints the
4974 value of that capability ("yes" or "no" indicating that the terminal does
4975 or does not have that capability).
4976 One might use this to make the output
4977 from a shell script less verbose on slow terminals, or limit command
4978 output to the number of lines on the screen:
4980 > set history=\`echotc lines\`
4984 Termcap strings may contain wildcards which will not echo correctly.
4985 One should use double quotes when setting a shell variable to a terminal
4986 capability string, as in the following example that places the date in
4989 > set tosl="\`echotc ts 0\`"
4991 > set frsl="\`echotc fs\`"
4993 > echo \-n "$tosl";date; echo \-n "$frsl"
4996 .Fl s\fR, nonexistent capabilities return the empty string rather
4997 than causing an error.
4999 .Fl v\fR, messages are verbose.
5010 See the description of the
5024 Treats the arguments as input to the
5025 shell and executes the resulting command(s) in the context
5026 of the current shell.
5027 This is usually used to execute commands
5028 generated as the result of command or variable substitution,
5029 because parsing occurs before these substitutions.
5032 (1) for a sample use of
5037 Executes the specified command in place of the current shell.
5042 The shell exits either with the value of the specified
5044 (an expression, as described under
5054 Brings the specified jobs (or, without arguments, the current job)
5055 into the foreground, continuing each if it is stopped.
5057 may be a number, a string,
5077 (which is a file inquiry operator as described under
5078 .Va File inquiry operators
5081 and returns the results as a
5082 space-separated list.
5084 .B foreach \fIname \fB(\fIwordlist\fB)
5090 Successively sets the variable
5094 and executes the sequence of commands between this command
5101 must appear alone on separate lines.) The builtin command
5103 may be used to continue the loop prematurely and
5106 to terminate it prematurely.
5107 When this command is read from the terminal, the loop is read once
5112 ) before any statements in
5113 the loop are executed.
5114 If you make a mistake typing in a
5115 loop at the terminal you can rub it out.
5119 Prints the system execution path.
5123 Prints the experimental version prefix.
5131 parameter is not recognized and words are
5132 delimited by null characters in the output.
5134 programs which wish to use the shell to filename expand a list of words.
5138 is filename and command-substituted to
5139 yield a string of the form
5141 The shell rewinds its
5142 input as much as possible, searches for a line of the
5145 , possibly preceded by blanks or tabs, and
5146 continues execution after that line.
5149 Prints a statistics line indicating how effective the
5150 internal hash table has been at locating commands (and avoiding
5155 is attempted for each component of the
5157 where the hash function indicates a possible hit, and
5158 in each component which does not begin with a
5163 (2), prints only the number and size of
5178 .B history \-c \fR(+)
5179 The first form prints the history event list.
5184 most recent events are printed or saved.
5186 .Fl h\fR, the history list is printed without leading numbers.
5189 is specified, timestamps are printed also in comment form.
5190 (This can be used to
5191 produce files suitable for loading with 'history \-L' or 'source \-h'.)
5193 .Fl r\fR, the order of printing is most recent
5194 first rather than oldest first.
5199 .Fl S\fR, the second form saves the history list to
5201 If the first word of the
5203 shell variable is set to a
5204 number, at most that many lines are saved.
5205 If the second word of
5209 , the history list is merged with the
5210 existing history file instead of replacing it (if there is one) and
5211 sorted by time stamp.
5212 (+) Merging is intended for an environment like
5214 with several shells in simultaneous use.
5215 If the second word of
5219 and the third word is set to
5221 , the history file update
5222 will be serialized with other shell sessions that would possibly like
5223 to merge history at exactly the same time.
5226 .Fl L\fR, the shell appends
5228 , which is presumably a
5229 history list saved by the
5230 .Fl S\fR option or the
5233 to the history list.
5235 .Fl L\fR, but the contents of
5238 into the history list and sorted by timestamp.
5248 `history \-L' is exactly like 'source \-h' except that it does not require a
5251 Note that login shells do the equivalent of
5261 is normally sourced before
5272 is set, the first and second forms print and save the literal
5273 (unexpanded) form of the history list.
5275 The last form clears the history list.
5285 such that it will exit on a hangup
5286 signal and arranges for the shell to send it a hangup signal when the shell
5288 Note that commands may set their own response to hangups, overriding
5290 Without an argument, causes the non-interactive shell only to
5291 exit on a hangup for the remainder of the script.
5298 .B if (\fIexpr\fB) \fIcommand
5301 (an expression, as described under
5304 evaluates true, then
5307 Variable substitution on
5309 happens early, at the same time it
5310 does for the rest of the
5314 must be a simple command, not an alias, a pipeline, a command list
5315 or a parenthesized command list, but it may have arguments.
5316 Input/output redirection occurs even if
5323 executed; this is a bug.
5325 .B if (\fIexpr\fB) then
5329 .B else if (\fIexpr2\fB) then
5341 is true then the commands to the
5344 are executed; otherwise if
5347 the commands to the second
5353 pairs are possible; only one
5359 part is likewise optional.
5364 must appear at the beginning of input lines;
5367 must appear alone on its input line or after an
5377 to the current environment.
5379 to remove a shared library.
5384 Lists the active jobs.
5386 .Fl l\fR, lists process
5387 IDs in addition to the normal information.
5388 On TCF systems, prints
5389 the site on which each job is executing.
5404 The first and second forms sends the specified
5407 is given, the TERM (terminate) signal) to the specified jobs or processes.
5409 may be a number, a string,
5420 Signals are either given by number or by name (as given in
5421 .Va /usr/include/signal.h
5422 , stripped of the prefix
5429 does not send a signal
5431 If the signal being sent is TERM (terminate)
5432 or HUP (hangup), then the job or process is sent a
5433 CONT (continue) signal as well.
5434 The third form lists the signal names.
5443 Limits the consumption by the current process and each
5444 process it creates to not individually exceed
5452 the current limit is printed; if no
5455 all limitations are given.
5457 .Fl h\fR flag is given, the
5458 hard limits are used instead of the current limits.
5460 hard limits impose a ceiling on the values of the current
5462 Only the super-user may raise the hard limits, but
5463 a user may lower or raise the current limits within the legal range.
5465 Controllable resources currently include (if supported by the OS):
5466 .Bl -tag -width pseudoterminals -compact -offset indent
5468 the maximum number of cpu-seconds to be used by each process
5470 the largest single file which can be created
5472 the maximum growth of the data+stack region via sbrk(2) beyond
5473 the end of the program text
5475 the maximum size of the automatically-extended stack region
5477 the size of the largest core dump that will be created
5479 the maximum amount of physical memory a process
5480 may have allocated to it at a given time
5482 the maximum amount of virtual memory a process
5483 may have allocated to it at a given time (address space)
5485 the maximum amount of virtual memory a process
5486 may have allocated to it at a given time
5488 the maximum amount of memory a process
5495 the maximum number of open files for this process
5496 .It Va pseudoterminals
5497 the maximum number of pseudo-terminals for this user
5499 the maximum number of kqueues allocated for this process
5501 the maximum number of threads for this process
5503 the maximum size which a process may lock into memory using mlock(2)
5505 the maximum number of simultaneous processes for this user id
5507 the maximum number of simultaneous threads (lightweight processes) for this
5510 the maximum number of threads for this process
5512 the maximum size of socket buffer usage for this user
5514 the maximum amount of swap space reserved or used for this user
5516 the maximum number of locks for this user
5518 the maximum number of POSIX advisory locks for this user
5520 the maximum number of pending signals for this user
5522 the maximum number of bytes in POSIX mqueues for this user
5524 the maximum nice priority the user is allowed to raise mapped from [19...-20]
5525 to [0...39] for this user
5527 the maximum realtime priority for this user
5529 the timeout for RT tasks in microseconds for this user.
5533 may be given as a (floating point or
5534 integer) number followed by a scale factor.
5538 the default scale is
5542 (1024 bytes); a scale factor of
5553 the default scaling is
5559 for hours, or a time of the
5562 giving minutes and seconds may be used.
5568 then the limitation on the specified
5570 is removed (this is equivalent to the
5576 names and scale factors, unambiguous
5577 prefixes of the names suffice.
5583 shell variable and reports on each user indicated
5586 who is logged in, regardless of when they last logged in.
5591 Terminates a login shell, replacing it with an instance of
5593 . This is one way to log off, included for
5598 Terminates a login shell.
5599 Especially useful if
5611 It identifies each type of
5612 special file in the listing with a special character:
5613 .Bl -tag -width x -offset indent -compact
5623 Named pipe (systems with named pipes only)
5625 Socket (systems with sockets only)
5627 Symbolic link (systems with symbolic links only)
5629 Hidden directory (AIX only) or context dependent (HP/UX only)
5631 Network special (HP/UX only)
5636 shell variable is set, symbolic links are identified
5637 in more detail (on only systems that have them, of course):
5642 Symbolic link to a non-directory
5645 Symbolic link to a directory
5648 Symbolic link to nowhere
5652 also slows down \fIls\-F\fR and causes partitions holding
5653 files pointed to by symbolic links to be mounted.
5657 shell variable is set to
5664 combination thereof (e.g.,
5666 ), they are used as flags to \fIls\-F\fR,
5679 is not the default, \fIls\-F\fR acts like
5686 , in which case it acts like
5688 \fIls\-F\fR passes its arguments to
5690 (1) if it is given any switches,
5693 generally does the right thing.
5695 The \fBls\-F\fR builtin can list files using different colors depending on the
5696 filetype or extension.
5699 shell variable and the
5701 environment variable.
5717 The first form migrates the process or job to the site specified or the
5718 default site determined by the system path.
5719 The second form is equivalent to
5724 current process to the specified site.
5726 itself can cause unexpected behavior, because the shell
5727 does not like to lose its tty.
5740 Available only if the shell was so compiled;
5750 Sets the scheduling priority for the shell to
5765 The super-user may specify negative
5767 .Sq nice \-number ...
5769 executed in a sub-shell, and the restrictions placed on
5781 such that it will ignore hangup signals.
5782 Note that commands may set their own response to hangups, overriding
5784 Without an argument, causes the non-interactive shell only to
5785 ignore hangups for the remainder of the script.
5795 Causes the shell to notify the user asynchronously when the status of any
5796 of the specified jobs (or, without %
5798 , the current job) changes,
5799 instead of waiting until the next prompt as is usual.
5801 may be a number, a string,
5820 Controls the action of the shell on interrupts.
5822 restores the default action of the shell on interrupts,
5823 which is to terminate shell scripts or to return to the
5824 terminal command input level.
5827 , causes all interrupts to be ignored.
5830 , causes the shell to execute a
5833 when an interrupt is received or a child process terminates because it was
5837 is ignored if the shell is running detached and in system
5840 ), where interrupts are disabled anyway.
5849 Without arguments, pops the directory stack and returns to the new top directory.
5855 'th entry in the stack.
5857 Finally, all forms of
5859 print the final directory stack,
5864 shell variable can be set to
5865 prevent this and the
5866 .Fl p\fR flag can be given to override
5871 .Fl v\fR flags have the same effect on
5880 Prints the names and values of all environment variables or,
5883 , the value of the environment variable
5895 Without arguments, exchanges the top two elements of the directory stack.
5900 without arguments does
5908 , pushes the current working directory onto the directory
5909 stack and changes to
5915 it is interpreted as the previous working directory
5917 .Va Filename substitution
5924 removes any instances of
5926 from the stack before pushing it onto the stack.
5934 directory stack around to be the top element and changes to it.
5943 directory, pushes it onto the top of the stack and changes to it.
5946 Finally, all forms of
5948 print the final directory stack,
5953 shell variable can be set to
5954 prevent this and the
5955 .Fl p\fR flag can be given to override
5960 .Fl v\fR flags have the same effect on
5967 Causes the internal hash table of the contents of the
5970 variable to be recomputed.
5974 shell variable is not set and new
5975 commands are added to directories in
5977 while you are logged
5981 , a new command will be found
5982 automatically, except in the special case where another command of
5983 the same name which is located in a different directory already
5984 exists in the hash table.
5985 Also flushes the cache of home directories
5986 built by tilde expansion.
5988 .B repeat \fIcount command
5992 which is subject to the same restrictions as the
5996 statement above, is executed
5999 I/O redirections occur exactly once, even if
6006 Changes the rootnode to //
6028 The first form prints the scheduled-event list.
6031 shell variable may be set to define the format in which
6032 the scheduled-event list is printed.
6033 The second form adds
6035 to the scheduled-event list.
6040 > sched 11:00 echo It\e's eleven o\e'clock.
6042 causes the shell to echo
6043 .Sq It's eleven o'clock .
6045 The time may be in 12-hour AM/PM format
6048 > sched 5pm set prompt='[%h] It\e's after 5; go home: >'
6050 or may be relative to the current time:
6052 > sched +2:15 /usr/lib/uucp/uucico \-r1 \-sother
6054 A relative time specification may not use AM/PM format.
6055 The third form removes item
6057 from the event list:
6058 .Bd -literal -offset indent
6060 1 Wed Apr 4 15:42 /usr/lib/uucp/uucico \-r1 \-sother
6061 2 Wed Apr 4 17:00 set prompt=[%h] It's after 5; go home: >
6064 1 Wed Apr 4 15:42 /usr/lib/uucp/uucico \-r1 \-sother
6067 A command in the scheduled-event list is executed just before the first
6068 prompt is printed after the time when the command is scheduled.
6069 It is possible to miss the exact time when the command is to be run, but
6070 an overdue command will execute at the next prompt.
6071 A command which comes due while the shell
6072 is waiting for user input is executed immediately.
6073 However, normal operation of an already-running command will not
6074 be interrupted so that a scheduled-event list element may be run.
6076 This mechanism is similar to, but not the same as, the
6079 command on some Unix systems.
6080 Its major disadvantage is that it may not run a command at exactly the
6082 Its major advantage is that because
6085 the shell, it has access to shell variables and other structures.
6086 This provides a mechanism for changing one's working environment
6087 based on the time of day.
6102 .B set [\-r] [\-f|\-l]
6126 The first form of the command prints the value of all shell variables.
6127 Variables which contain more than a single word print as a
6128 parenthesized word list.
6129 The second form sets
6136 The fourth form sets
6138 to the list of words in
6140 In all cases the value is command and filename expanded.
6142 .Fl r\fR is specified, the value is set read-only.
6145 .Fl l\fR are specified, set only unique words keeping their order.
6146 .Fl f\fR prefers the first occurrence of a word, and
6148 The fifth form sets the
6155 this component must already exist.
6156 The sixth form lists only the names of all shell variables that are read-only.
6157 The seventh form makes
6159 read-only, whether or not it has a value.
6160 The eighth form is the same as the third form, but
6163 read-only at the same time.
6166 These arguments can be repeated to set and/or make read-only multiple variables
6167 in a single set command.
6168 Note, however, that variable expansion
6169 happens for all arguments before any setting occurs.
6177 or separated from both by
6178 whitespace, but cannot be adjacent to only one or the other.
6188 Without arguments, prints the names and values of all environment variables.
6191 , sets the environment variable
6197 , to the null string.
6207 .B setspath\fR LOCAL|
6213 Sets the system execution path.
6219 Tells the shell to believe that the terminal capability
6225 No sanity checking is done.
6226 Concept terminal users may have to
6229 wrapping at the rightmost column.
6241 Controls which tty modes (see
6242 .Va Terminal management
6244 the shell does not allow to change.
6256 set of tty modes respectively; without
6263 Without other arguments,
6265 lists the modes in the chosen set
6266 which are fixed on (`+mode') or off (`\-mode').
6267 The available modes, and thus the display, vary from system to system.
6269 .Fl a\fR, lists all tty modes in the chosen set
6270 whether or not they are fixed.
6281 or removes control from
6285 .Sq setty +echok echoe
6288 mode on and allows commands
6291 mode on or off, both when the shell is executing commands.
6296 Set the experimental version prefix to
6307 Without arguments, discards
6309 [1] and shifts the members of
6314 not to be set or to have
6315 less than one word as value.
6328 The shell reads and executes commands from
6330 The commands are not placed on the history list.
6333 are given, they are placed in
6337 commands may be nested;
6338 if they are nested too deeply the shell may run out of file descriptors.
6341 at any level terminates all nested
6345 .Fl h\fR, commands are placed on the history list instead of being
6354 Stops the specified jobs or processes which are executing in the background.
6356 may be a number, a string,
6375 Causes the shell to stop in its tracks, much as if it had
6376 been sent a stop signal with
6378 This is most often used to
6379 stop shells started by
6383 .B switch (\fIstring\fB)
6401 Each case label is successively matched, against the
6404 which is first command and filename expanded.
6405 The file metacharacters
6412 in the case labels, which are variable expanded.
6414 of the labels match before a
6416 label is found, then
6417 the execution begins after the default label.
6419 label and the default label must appear at the beginning of
6423 causes execution to continue
6426 Otherwise control may fall through case
6427 labels and default labels as in C.
6428 If no label matches and
6429 there is no default, execution continues after the
6434 Lists the values of all terminal capabilities (see
6443 (or the current value of
6447 is given) has an entry in the hosts termcap(5) or
6448 terminfo(5) database. Prints the terminal type to stdout and returns 0
6449 if an entry is present otherwise returns 1.
6456 (which must be a simple command, not an alias,
6457 a pipeline, a command list or a parenthesized command list)
6458 and prints a time summary as described under the
6461 If necessary, an extra shell is created to print the time statistic when
6462 the command completes.
6465 , prints a time summary for the current shell and its
6471 Sets the file creation mask to
6473 , which is given in octal.
6474 Common values for the mask are
6475 002, giving all access to the group and read and execute access to others, and
6476 022, giving read and execute access to the group and others.
6479 , prints the current file creation mask.
6484 Removes all aliases whose names match
6486 `unalias *' thus removes all aliases.
6487 It is not an error for nothing to be
6494 Removes all completions whose names match
6496 `uncomplete *' thus removes all completions.
6497 It is not an error for nothing to be
6502 Disables use of the internal hash table to speed location of
6508 Sets the universe to
6516 Removes the limitation on
6525 .Fl h\fR, the corresponding hard limits are removed.
6526 Only the super-user may do this.
6529 may not exit successful, since most systems
6534 .Fl f\fR errors are ignored.
6537 Removes all variables whose names match
6539 , unless they are read-only.
6540 `unset *' thus removes all variables unless they are read-only;
6542 It is not an error for nothing to be
6545 .B unsetenv \fIpattern
6546 Removes all environment variables whose names match
6548 `unsetenv *' thus removes all environment variables;
6550 It is not an error for nothing to be
6559 Without arguments, prints
6583 The shell waits for all background jobs.
6584 If the shell is interactive, an
6585 interrupt will disrupt the wait and cause the shell to print the names and job
6586 numbers of all outstanding jobs.
6591 Sets the universe to
6596 An alternate name for the
6598 builtin command (q.v.).
6599 Available only if the shell was so compiled;
6607 Reports all known instances of
6609 , including aliases, builtins and
6616 Displays the command that will be executed by the shell after substitutions,
6619 The builtin command is just like
6621 (1), but it correctly reports
6623 aliases and builtins and is 10 to 100 times faster.
6635 Executes the commands between the
6641 (an expression, as described under
6648 must appear alone on their input lines.
6652 may be used to terminate or continue the
6654 If the input is a terminal, the user is prompted the first time
6655 through the loop as with
6658 .Ss "Special aliases (+)"
6659 If set, each of these aliases executes automatically at the indicated time.
6660 They are all initially undefined.
6663 Runs when the shell wants to ring the terminal bell.
6666 Runs after every change of working directory.
6667 For example, if the user is
6668 working on an X window system using
6670 (1) and a re-parenting window
6671 manager that supports title bars such as
6676 > alias cwdcmd 'echo \-n "^[]2;${HOST}:$cwd ^G"'
6678 then the shell will change the title of the running
6681 to be the name of the host, a colon, and the full current working directory.
6682 A fancier way to do that is
6684 > alias cwdcmd 'echo \-n "^[]2;${HOST}:$cwd^G^[]1;${HOST}^G"'
6686 This will put the hostname and working directory on the title bar but
6687 only the hostname in the icon manager menu.
6697 may cause an infinite loop.
6698 It is the author's opinion that anyone doing
6699 so will get what they deserve.
6703 Runs before each command gets executed, or when the command changes state.
6706 , but it does not print builtins.
6709 > alias jobcmd 'echo \-n "^[]2\e;\e!#:q^G"'
6713 will put the command string in the xterm title bar.
6720 The command name for which help
6721 is sought is passed as sole argument.
6722 For example, if one does
6725 > alias helpcommand '\e!:1 --help'
6727 then the help display of the command itself will be invoked, using the GNU
6728 help calling convention.
6729 Currently there is no easy way to account for various calling conventions (e.g.,
6732 ), except by using a table of many commands.
6739 This provides a convenient means for
6740 checking on common but infrequent changes such as new mail.
6747 > alias periodic checknews
6751 (1) program runs every 30 minutes.
6756 is unset or set to 0,
6763 Runs just before each prompt is printed.
6764 For example, if one does
6771 (1) runs just before the shell prompts for each command.
6772 There are no limits on what
6774 can be set to do, but discretion
6779 Runs before each command gets executed.
6782 > alias postcmd 'echo \-n "^[]2\e;\e!#:q^G"'
6786 will put the command string in the xterm title bar.
6790 Specifies the interpreter for executable scripts which do not themselves
6791 specify an interpreter.
6792 The first word should be a full path name to the
6793 desired interpreter (e.g.,
6796 .Sq /usr/local/bin/tcsh
6798 .Ss "Special shell variables"
6799 The variables described in this section have special meaning to the shell.
6828 startup; they do not change thereafter unless changed by the user.
6840 The shell synchronizes
6847 with the environment variables of the same names:
6848 whenever the environment variable changes the shell changes the corresponding
6849 shell variable to match (unless the shell variable is read-only) and vice
6855 have identical meanings, they
6856 are not synchronized in this manner, and that the shell automatically
6857 converts between the different formats of
6863 If set, filename completion adds
6865 to the end of directories and a space
6866 to the end of normal files when they are matched exactly.
6872 's autolock feature uses its value instead of
6873 the local username for kerberos authentication.
6876 If set, all times are shown in 12-hour AM/PM format.
6879 This variable selects what is propagated to the value of the
6881 variable. For more information see the description of the
6886 The arguments to the shell.
6887 Positional parameters are taken from
6895 Set by default, but usually empty in interactive shells.
6897 .B autocorrect \fR(+)
6900 editor command is invoked automatically before
6901 each completion attempt.
6903 .B autoexpand \fR(+)
6906 editor command is invoked automatically
6907 before each completion attempt. If this is set to
6910 only history will be expanded and a second completion will expand filenames.
6913 If set, possibilities are listed after an ambiguous completion.
6916 , possibilities are listed only when no new
6917 characters are added by completion.
6919 .B autologout \fR(+)
6920 The first word is the number of minutes of inactivity before automatic
6922 The optional second word is the number of minutes of inactivity
6923 before automatic locking.
6924 When the shell automatically logs out, it prints
6932 When the shell automatically locks, the user is required to enter his password
6933 to continue working.
6934 Five incorrect attempts result in automatic logout.
6937 (automatic logout after 60 minutes, and no locking) by default
6938 in login and superuser shells, but not if the shell thinks it is running
6939 under a window system (i.e., the
6941 environment variable is set),
6942 the tty is a pseudo-tty (pty) or the shell was not so compiled (see the
6951 .B autorehash \fR(+)
6952 If set, the internal hash table of the contents of the directories in the
6954 variable will be recomputed if a command is not found in the hash
6956 In addition, the list of available commands will be rebuilt for each
6957 command completion or spelling correction attempt if set to
6960 `correct' respectively; if set to
6962 , this will be done for both
6965 .B backslash_quote \fR(+)
6967 If set, backslashes (`\e') always quote
6974 complex quoting tasks easier, but it can cause syntax errors in
6979 The file name of the message catalog.
6982 as a message catalog instead of
6987 A list of directories in which
6990 subdirectories if they aren't found in the current directory.
6995 requires a directory
6997 , and will not go to the
6999 directory if it's omitted.
7000 This is set by default.
7003 If set, it enables color display for the builtin \fBls\-F\fR and it passes
7004 .Fl \-color=auto\fR to
7006 Alternatively, it can be set to only
7009 to enable color to only one command.
7011 it to nothing is equivalent to setting it to \fB(ls\-F ls)\fR.
7014 If set, it enables color escape sequence for NLS message files.
7015 And display colorful NLS messages.
7018 If set, the command which was passed to the shell with the
7022 .B compat_expr \fR(+)
7023 If set, the shell will evaluate expressions right to left, like the original
7029 , the completion becomes case insensitive.
7032 , completion ignores case and considers
7033 hyphens and underscores to be equivalent; it will also treat
7034 periods, hyphens and underscores (`.',
7042 , completion matches uppercase and underscore
7043 characters explicitly and matches lowercase and hyphens in a
7044 case-insensitive manner; it will treat periods, hyphens and underscores
7048 If set to a list of commands, the shell will continue the listed
7049 commands, instead of starting a new one.
7051 .B continue_args \fR(+)
7052 Same as continue, but the shell will execute:
7055 echo \`pwd\` $argv > ~/.<cmd>_pause; %<cmd>
7061 , commands are automatically spelling-corrected.
7064 , commands are automatically completed.
7067 , the entire command line is corrected.
7069 .B csubstnonl \fR(+)
7070 If set, newlines and carriage returns in command substitution are
7075 The full pathname of the current directory.
7088 th directory from the directory
7089 stack rather than rotating it to the top.
7092 The default location in which
7103 is normally sourced before
7113 An array of all the directories on the directory stack.
7114 `$dirstack[1]' is the current working directory,
7116 the first directory on the stack, etc.
7117 Note that the current working directory is
7122 directory stack substitutions, etc.
7123 One can change the stack arbitrarily by setting
7126 but the first element (the current working directory) is always correct.
7134 Has an effect iff 'dspm' is listed as part of the
7139 , it enables display and editing EUC-kanji(Japanese) code.
7142 , it enables display and editing Shift-JIS(Japanese) code.
7145 , it enables display and editing Big5(Chinese) code.
7148 , it enables display and editing Utf8(Unicode) code.
7149 If set to the following format, it enables display and editing of original
7150 multi-byte code format:
7153 > set dspmbyte = 0000....(256 bytes)....0000
7158 Each character of 256 characters
7159 corresponds (from left to right) to the ASCII codes 0x00, 0x01, ... 0xff.
7162 .\" (position in this table?)
7163 is set to number 0,1,2 and 3.
7164 Each number has the following meaning:
7166 0 ... not used for multi-byte characters.
7168 1 ... used for the first byte of a multi-byte character.
7170 2 ... used for the second byte of a multi-byte character.
7172 3 ... used for both the first byte and second byte of a multi-byte character.
7173 .\" SHK: I tried my best to get the following to be grammatically correct.
7174 .\" However, I still don't understand what's going on here.
7176 .\" following example, there are three bytes, but the text seems to refer to
7177 .\" each nybble as a character.
7178 What's going on here? It this 3-byte code
7179 .\" in the table? The text above seems to imply that there are 256
7180 .\" characters/bytes in the table.
7181 If I get some more info on this (perhaps
7182 .\" a complete example), I could fix the text to be grammatically correct.
7183 .\" (steve.kelem@xilinx.com 1999/09/13)
7189 , the first character (means 0x00 of the ASCII code) and
7190 second character (means 0x01 of ASCII code) are set to
7193 used for multi-byte characters.
7194 The 3rd character (0x02) is set to '1',
7195 indicating that it is used for the first byte of a multi-byte character.
7196 The 4th character(0x03) is set '3'.
7197 It is used for both the first byte and
7198 the second byte of a multi-byte character.
7199 The 5th and 6th characters
7200 (0x04,0x05) are set to '2', indicating that they are used for the second
7201 byte of a multi-byte character.
7203 The GNU fileutils version of ls cannot display multi-byte
7204 filenames without the -N ( --literal ) option.
7206 this version, set the second word of dspmbyte to "ls".
7208 example, "ls-F -l" cannot display multi-byte filenames.
7212 This variable can only be used if KANJI and DSPMBYTE has been defined at
7219 removes any instances of
7221 from the stack before pushing it onto the stack.
7224 If set, each command with its arguments is echoed just before it is
7226 For non-builtin commands all expansions occur before
7228 Builtin commands are echoed before command and filename
7229 substitution, because these substitutions are then done selectively.
7231 .Fl x\fR command line option.
7233 .B echo_style \fR(+)
7243 Don't echo a newline if the first argument is
7249 Recognize backslashed escape sequences in echo strings.
7254 flag and backslashed escape sequences; the default
7262 Set by default to the local system default.
7263 The BSD and System V
7264 options are described in the
7266 (1) man pages on the appropriate
7271 If set, the command-line editor is used.
7272 Set by default in interactive
7276 A list of command names for the
7278 editor command to match.
7284 environment variables will be used instead.
7291 prompt sequences (see the
7293 shell variable) indicate skipped directories with an ellipsis (`...')
7298 The user's effective user ID.
7301 The first matching passwd entry name corresponding to the effective user ID.
7304 Lists file name suffixes to be ignored by completion.
7309 , completion is always used and this variable is ignored
7312 is unset, then the traditional
7317 , filename completion is used.
7320 The user's real group ID.
7323 If set, wild-card glob patterns will match files and directories beginning
7336 file glob patterns will match any string of
7337 characters including
7339 traversing any existing sub-directories.
7341 `ls **.c' will list all the .c files in the current directory tree).
7342 If used by itself, it will match zero or more sub-directories
7344 .Sq ls /usr/include/**/time.h
7345 will list any file named
7347 in the /usr/include directory tree; whereas
7348 .Sq ls /usr/include/**time.h
7349 will match any file in the /usr/include directory tree ending in
7352 To prevent problems with recursion, the
7354 glob-pattern will not
7355 descend into a symbolic link containing a directory.
7361 The user's group name.
7364 If set, the incremental search match (in
7368 ) and the region between the mark and the cursor are
7369 highlighted in reverse video.
7371 Highlighting requires more frequent terminal writes, which introduces extra
7372 overhead. If you care about terminal performance, you may want to leave this
7376 A string value determining the characters used in \fBHistory
7377 substitution\fR (q.v.).
7378 The first character of its value is used as
7379 the history substitution character, replacing the default character
7381 The second character of its value replaces the character
7384 quick substitutions.
7387 Controls handling of duplicate entries in the history list.
7389 `all' only unique history events are entered in the history list.
7393 and the last history event is the same as the current
7394 command, then the current command is not entered in the history.
7398 and the same event is found in the history list, that
7399 old event gets erased and the current one gets inserted.
7403 options renumber history events so there are no gaps.
7406 The default location in which
7417 useful when sharing the same home directory between different machines,
7418 or when saving separate histories on different terminals.
7421 is normally sourced before
7431 If set, builtin and editor commands and the
7434 use the literal (unexpanded) form of lines in the history list.
7437 .Va toggle-literal-history
7441 The first word indicates the number of history events to save.
7443 optional second word (+) indicates the format in which history is
7444 printed; if not given,
7447 The format sequences
7448 are described below under
7450 ; note the variable meaning of
7457 Initialized to the home directory of the invoker.
7462 refers to this variable.
7465 If set to the empty string or
7467 and the input device is a terminal,
7470 command (usually generated by the user by typing
7471 `^D' on an empty line) causes the shell to print `Use "exit" to leave
7472 tcsh.' instead of exiting.
7473 This prevents the shell from accidentally
7475 Historically this setting exited after 26 successive
7476 EOF's to avoid infinite loops.
7489 is used, i.e., the shell exits on a
7493 .B implicitcd \fR(+)
7494 If set, the shell treats a directory name typed as a command as though
7495 it were a request to change to that directory.
7499 the change of directory is echoed to the standard output.
7501 is inhibited in non-interactive shell scripts, or for command strings
7502 with more than one word.
7503 Changing directory takes precedence over
7504 executing a like-named command, but it is done after alias
7506 Tilde and variable expansions work as expected.
7513 , puts the editor into that input mode
7514 at the beginning of each line.
7517 Controls handling of duplicate entries in the kill ring.
7519 `all' only unique strings are entered in the kill ring.
7521 `prev' and the last killed string is the same as the current killed
7522 string, then the current string is not entered in the ring.
7526 and the same string is found in the kill ring, the old
7527 string is erased and the current one is inserted.
7530 Indicates the number of killed strings to keep in memory.
7534 If unset or set to less than
7536 , the shell will only
7537 keep the most recently killed string.
7538 Strings are put in the killring by the editor commands that delete
7539 (kill) strings of text, e.g.
7540 .Va backward-delete-word
7543 , etc, as well as the
7544 .Va copy-region-as-kill
7548 editor command will yank the most recently killed string
7549 into the command-line, while
7554 can be used to yank earlier killed strings.
7563 , or any combination thereof (e.g.,
7566 are used as flags to \fIls\-F\fR, making it act like
7571 or a combination (e.g.,
7576 files (even if they start with a
7585 sorts across instead of down.
7586 If the second word of
7588 is set, it is used as the path to
7592 If set, all jobs are listed when a job is suspended.
7596 the listing is in long format.
7599 If set, the \fIls\-F\fR builtin command shows the type of file to which
7600 each symbolic link points.
7603 The maximum number of items which the
7606 will list without asking first.
7608 .B listmaxrows \fR(+)
7609 The maximum number of rows of items which the
7612 command will list without asking first.
7615 Set by the shell if it is a login shell.
7616 Setting or unsetting it
7617 within a shell has no effect.
7624 before a normal logout,
7627 an automatic logout, and
7629 if the shell was killed by a hangup
7638 A list of files and directories to check for incoming mail, optionally
7639 preceded by a numeric word.
7640 Before each prompt, if 10 minutes have
7641 passed since the last check, the shell checks each file and says `You
7642 have new mail.' (or, if
7644 contains multiple files, `You have
7647 .') if the filesize is greater than zero in size
7648 and has a modification time greater than its access time.
7653 If you are in a login shell, then no mail file is reported unless it has
7654 been modified after the time the shell has started up, to prevent
7655 redundant notifications.
7656 Most login programs will tell you whether or not
7657 you have mail when you log in.
7659 If a file specified in
7661 is a directory, the shell will count each
7662 file within that directory as a separate message, and will report `You have
7670 This functionality is provided primarily for those systems which store mail
7671 in this manner, such as the Andrew Mail System.
7673 If the first word of
7675 is numeric it is taken as a different mail
7676 checking interval, in seconds.
7678 Under very rare circumstances, the shell may report
7682 .Sq You have new mail.
7688 , completion never beeps.
7691 , it beeps only when there is no match.
7694 , it beeps when there are multiple matches.
7697 , it beeps when there is one exact and other longer matches.
7703 If set, beeping is completely disabled.
7708 If set, restrictions are placed on output redirection to insure that files
7709 are not accidentally destroyed and that
7711 redirections refer to existing
7712 files, as described in the
7717 If set, disable the printing of
7722 specifiers at the change of hour.
7726 .Va Filename substitution
7728 .Va Directory stack substitution
7729 (q.v.) are inhibited.
7730 This is most useful in shell scripts which do not deal
7731 with filenames, or after a list of filenames has been obtained and further
7732 expansions are not desirable.
7735 If set and the shell supports Kanji (see the
7738 it is disabled so that the meta key can be used.
7742 .Va Filename substitution
7744 .Va Directory stack substitution
7745 (q.v.) which does not match any
7746 existing files is left untouched rather than causing an error.
7747 It is still an error for the substitution to be
7750 still gives an error.
7753 A list of directories (or glob-patterns which match directories; see
7754 .Va Filename substitution
7755 ) that should not be
7758 completion operation.
7759 This is usually used to exclude directories which
7760 take too much time to
7766 If set, the shell announces job completions asynchronously.
7767 The default is to present job completions just before printing a prompt.
7770 The user's real organization ID.
7774 The old working directory, equivalent to the
7787 If set, enable the printing of padding '0' for hours, in 24 and 12 hour
7789 E.G.: 07:45:42 vs. 7:45:42.
7792 To retain compatibily with older versions numeric variables starting with
7793 0 are not interpreted as octal. Setting this variable enables proper octal
7797 A list of directories in which to look for executable commands.
7798 A null word specifies the current directory.
7801 variable then only full path names will execute.
7803 is set by the shell at startup from the
7808 does not exist, to a system-dependent default
7810 .Sq (/usr/local/bin /usr/bsd /bin /usr/bin .)
7816 depending on how it was compiled; see the
7819 A shell which is given neither the
7822 hashes the contents of the directories in
7830 If one adds a new command to a directory in
7833 is active, one may need to do a
7835 for the shell to find it.
7837 .B printexitvalue \fR(+)
7838 If set and an interactive program exits with a non-zero status, the shell
7844 The string which is printed before reading each command from the terminal.
7846 may include any of the following formatting sequences (+), which
7847 are replaced by the given information:
7853 The current working directory.
7856 The current working directory, but with one's home directory
7859 and other users' home directories represented by
7861 .Va Filename substitution
7862 `~user' substitution
7863 happens only if the shell has already used
7867 in the current session.
7874 The trailing component of the current working directory, or
7876 trailing components if a digit
7883 , the number of skipped components precede
7884 the trailing component(s) in the format
7890 shell variable is set, skipped components
7891 are represented by an ellipsis so the whole becomes
7893 `~' substitution is done as in
7898 is ignored when counting trailing components.
7901 Like %c, but without
7906 The current history event number.
7912 The hostname up to the first
7916 Start (stop) standout mode.
7919 Start (stop) boldfacing mode.
7922 Start (stop) underline mode.
7925 The time of day in 12-hour AM/PM format.
7930 , but in 24-hour format (but see the
7937 time of day in 12-hour AM/PM format, with seconds.
7942 , but in 24-hour format (but see the
7966 The effective user name.
8005 Clears from the end of the prompt to end of the display or the end of the line.
8008 Expands the shell or environment variable name immediately after the
8012 `>' (or the first character of the
8017 (or the second character of
8027 as a literal escape sequence.
8028 It should be used only to change terminal attributes and
8029 should not move the cursor location.
8031 cannot be the last sequence in
8035 The return code of the command executed just before the prompt.
8040 , the status of the parser.
8043 , the corrected string.
8046 , the history string.
8057 are available in only
8058 eight-bit-clean shells; see the
8062 The bold, standout and underline sequences are often used to distinguish a
8066 > set prompt = "%m [%h] %B[%@]%b [%/] you rang? "
8070 [/usr/accts/sys] you rang? _
8087 on the change of hour (i.e,
8094 in interactive shells.
8098 The string with which to prompt in
8103 after lines ending in
8105 The same format sequences may be used as in
8108 note the variable meaning of
8112 in interactive shells.
8115 The string with which to prompt when confirming automatic spelling correction.
8116 The same format sequences may be used as in
8119 note the variable meaning of
8122 .Sq CORRECT>%R (y|n|e|a)?
8123 in interactive shells.
8125 .B promptchars \fR(+)
8126 If set (to a two-character string), the
8128 formatting sequence in the
8130 shell variable is replaced with the first character for
8131 normal users and the second character for the superuser.
8133 .B pushdtohome \fR(+)
8136 without arguments does
8141 .B pushdsilent \fR(+)
8146 do not print the directory stack.
8149 If set, completion completes on an exact match even if a longer match is
8152 .B recognize_only_executables \fR(+)
8153 If set, command listing displays only files in the path that are
8158 If set, the user is prompted before
8163 The string to print on the right-hand side of the screen (after
8164 the command input) when the prompt is being displayed on the left.
8165 It recognizes the same formatting characters as
8167 It will automatically disappear and reappear as necessary, to ensure that
8168 command input isn't obscured, and will appear only if the prompt,
8169 command input, and itself will fit together on the first line.
8174 will be printed after
8175 the prompt and before the command input.
8178 If set, the shell does
8181 If the first word is set to a number, at most that many directory stack
8185 If set, the shell does
8188 If the first word is set to a number, at most that many lines are saved.
8189 (The number should be less than or equal to the number
8192 if it is set to greater than the number of
8196 entries will be saved)
8197 If the second word is set to
8199 , the history list is merged with
8200 the existing history file instead of replacing it (if there is one) and
8201 sorted by time stamp and the most recent events are retained.
8202 If the second word of
8206 and the third word is set to
8207 `lock', the history file update will be serialized with other shell sessions
8208 that would possibly like to merge history at exactly the same time. (+)
8211 The format in which the
8213 builtin command prints scheduled events;
8217 The format sequences are described above under
8220 note the variable meaning of
8224 The file in which the shell resides.
8225 This is used in forking
8226 shells to interpret files which have execute bits set, but
8227 which are not executable by the system.
8228 (See the description
8230 .Va Builtin and non-builtin command execution
8231 .) Initialized to the
8232 (system-dependent) home of the shell.
8235 The number of nested shells.
8236 Reset to 1 in login shells.
8241 The exit status from the last command or backquote expansion, or any
8242 command in a pipeline is propagated to
8248 This default does not match what POSIX mandates (to return the
8249 status of the last command only). To match the POSIX behavior, you need
8256 variable is unset, the exit status of a pipeline
8257 is determined only from the last command in the pipeline, and the exit
8258 status of a backquote expansion is
8263 If a command terminated abnormally, then 0200 is added to the status.
8264 Builtin commands which fail return exit status
8267 commands return status
8272 Can be set to several different values to control symbolic link (`symlink')
8278 , whenever the current directory changes to a directory
8279 containing a symbolic link, it is expanded to the real name of the directory
8280 to which the link points.
8281 This does not work for the user's home directory;
8286 , the shell tries to construct a current directory
8287 relative to the current directory before the link was crossed.
8290 ing through a symbolic link and then
8293 returns one to the original directory.
8294 This affects only builtin commands
8295 and filename completion.
8299 , the shell tries to fix symbolic links by actually expanding
8300 arguments which look like path names.
8301 This affects any command, not just
8303 Unfortunately, this does not work for hard-to-recognize filenames,
8304 such as those embedded in command options.
8305 Expansion may be prevented by
8307 While this setting is usually the most convenient, it is sometimes
8308 misleading and sometimes confusing when it fails to recognize an argument
8309 which should be expanded.
8310 A compromise is to use
8315 (bound by default to ^X-n) when necessary.
8317 Some examples are in order.
8318 First, let's set up some play directories:
8322 > mkdir from from/src to
8324 > ln \-s from/src to/dst
8326 Here's the behavior with
8330 > cd /tmp/to/dst; echo $cwd
8338 here's the behavior with
8344 > cd /tmp/to/dst; echo $cwd
8352 here's the behavior with
8358 > cd /tmp/to/dst; echo $cwd
8366 and here's the behavior with
8371 > cd /tmp/to/dst; echo $cwd
8379 > cd /tmp/to/dst; echo $cwd
8383 > cd ".."; echo $cwd
8397 expansion 1) works just like
8402 , 2) is prevented by quoting, and 3) happens before
8403 filenames are passed to non-builtin commands.
8407 The version number of the shell in the format
8412 is the major release number,
8424 .Va Startup and shutdown
8427 If set to a number, then the
8429 builtin (q.v.) executes automatically
8430 after each command which takes more than that many CPU seconds.
8431 If there is a second word, it is used as a format string for the output
8435 (u) The following sequences may be used in the
8442 The time the process spent in user mode in cpu seconds.
8445 The time the process spent in kernel mode in cpu seconds.
8448 The elapsed (wall clock) time in seconds.
8451 The CPU percentage computed as (%U + %S) / %E.
8454 Number of times the process was swapped.
8457 The average amount in (shared) text space used in Kbytes.
8460 The average amount in (unshared) data/stack space used in Kbytes.
8463 The total space used (%X + %D) in Kbytes.
8466 The maximum memory the process had in use at any time in Kbytes.
8469 The number of major page faults (page needed to be brought from disk).
8472 The number of minor page faults.
8475 The number of input operations.
8478 The number of output operations.
8481 The number of socket messages received.
8484 The number of socket messages sent.
8487 The number of signals received.
8490 The number of voluntary context switches (waits).
8493 The number of involuntary context switches.
8496 Only the first four sequences are supported on systems without BSD resource
8498 The default time format is
8499 .Sq %Uu %Ss %E %P %X+%Dk %I+%Oio %Fpf+%Ww
8501 systems that support resource usage reporting and
8504 systems that do not.
8506 Under Sequent's DYNIX/ptx, %X, %D, %K, %r and %s are not
8507 available, but the following additional sequences are:
8512 The number of system calls performed.
8515 The number of pages which are zero-filled on demand.
8518 The number of times a process's resident set size was increased by the kernel.
8521 The number of times a process's resident set size was decreased by the kernel.
8524 The number of read system calls performed.
8527 The number of write system calls performed.
8530 The number of reads from raw disk devices.
8533 The number of writes to raw disk devices.
8536 and the default time format is
8537 .Sq %Uu %Ss %E %P %I+%Oio %Fpf+%Ww
8538 Note that the CPU percentage can be higher than 100% on multi-processors.
8542 The period, in minutes, between executions of the
8547 The name of the tty, or empty if not attached to one.
8550 The user's real user ID.
8553 The user's login name.
8556 If set, causes the words of each
8557 command to be printed, after history substitution (if any).
8559 .Fl v\fR command line option.
8562 The version ID stamp.
8563 It contains the shell's version number (see
8566 origin, release date, vendor, operating system and machine (see
8572 ) and a comma-separated
8573 list of options which were set at compile time.
8574 Options which are set by default in the distribution are noted.
8580 The shell is eight bit clean; default
8583 The shell is not eight bit clean
8586 The shell is multibyte encoding clean (like UTF-8)
8589 The system's NLS is used; default for systems with NLS
8592 Login shells execute
8594 before instead of after
8598 before instead of after
8606 for security; default
8615 (1)\-style editing is the default rather than
8620 Login shells drop DTR when exiting
8628 is an alternate name for
8636 Kanji is used if appropriate according to locale settings,
8639 shell variable is set
8648 .Sq #!<program> <args>
8649 convention is emulated when executing shell scripts
8654 builtin is available
8657 The shell attempts to set the
8659 environment variable
8662 The shell verifies your password with the kerberos server if local
8663 authentication fails.
8666 shell variable or the
8668 environment variable override your local username if set.
8671 An administrator may enter additional strings to indicate differences
8672 in the local version.
8677 If unset, various key bindings change behavior to be more
8680 word boundaries are determined by
8682 versus other characters.
8684 If set, various key bindings change behavior to be more
8687 word boundaries are determined by
8690 versus other characters;
8691 cursor behavior depends upon current vi mode (command, delete, insert, replace).
8693 This variable is unset by
8703 may be explicitly set or unset by the user after those
8705 operations if required.
8708 .B visiblebell \fR(+)
8709 If set, a screen flash is used rather than the audible bell.
8714 A list of user/terminal pairs to watch for logins and logouts.
8715 If either the user is
8717 all terminals are watched for the given user
8723 watches all users and terminals.
8727 set watch = (george ttyd1 any console $user any)
8729 reports activity of the user
8731 on ttyd1, any user on the console, and
8732 oneself (or a trespasser) on any terminal.
8734 Logins and logouts are checked every 10 minutes by default, but the first
8737 can be set to a number to check every so many minutes.
8740 set watch = (1 any any)
8742 reports any login/logout once every minute.
8743 For the impatient, the
8745 builtin command triggers a
8749 are reported (as with the
8757 shell variable controls the format of
8763 The format string for
8766 The following sequences
8767 are replaced by the given information:
8773 The name of the user who logged in/out.
8776 The observed action, i.e.,
8786 The terminal (tty) on which the user logged in/out.
8789 The full hostname of the remote host, or
8791 if the login/logout was
8792 from the local host.
8795 The hostname of the remote host up to the first
8797 The full name is printed if it is an IP address or an X Window System display.
8800 %M and %m are available on only systems that store the remote hostname in
8803 .Sq %n has %a %l from %m.
8807 which don't store the remote hostname.
8811 A list of non-alphanumeric characters to be considered part of a word by the
8815 etc., editor commands.
8816 If unset, the default value is determined based on the state of
8823 is used as the default;
8828 is used as the default.
8837 The number of columns in the terminal.
8839 .Va Terminal management
8842 Used by X Window System (see
8845 If set, the shell does not set
8850 The pathname to a default editor.
8853 editor command if the
8856 shell variable is unset.
8859 environment variable.
8872 Initialized to the name of the machine on which the shell
8873 is running, as determined by the
8878 Initialized to the type of machine on which the shell
8879 is running, as determined at compile time.
8880 This variable is obsolete and
8881 will be removed in a future version.
8884 A colon-separated list of directories in which the
8887 command looks for command documentation.
8890 Gives the preferred character environment.
8892 .Va Native Language System support
8895 If set, only ctype character handling is changed.
8897 .Va Native Language System support
8900 The number of lines in the terminal.
8902 .Va Terminal management
8905 The format of this variable is reminiscent of the
8907 file format; a colon-separated list of expressions of the form
8912 " is a two-character variable name.
8914 variables with their associated defaults are:
8921 Normal (non-filename) text
8951 Missing file (defaults to fi)
8954 Orphaned symbolic link (defaults to ln)
8963 End code (replaces lc+no+rc)
8967 You need to include only the variables you want to change from
8970 File names can also be colorized based on filename extension.
8971 This is specified in the
8973 variable using the syntax
8975 For example, using ISO 6429 codes, to color
8976 all C\-language source files blue you would specify
8978 This would color all files ending in
8982 Control characters can be written either in C\-style\-escaped
8983 notation, or in stty\-like ^\-notation.
8984 The C\-style notation
8987 for Escape, \fB\_\fR for a normal space character,
8994 can be used to override the default interpretation of
9003 Each file will be written as
9014 code is undefined, the sequence
9018 will be used instead.
9019 This is generally more convenient
9020 to use, but less general.
9021 The left, right and end codes are
9022 provided so you don't have to type common parts over and over
9023 again and to support weird terminals; you will generally not
9024 need to change them at all unless your terminal does not use
9025 ISO 6429 color sequences but a different system.
9027 If your terminal does use ISO 6429 color codes, you can
9028 compose the type codes (i.e., all except the
9035 codes) from numerical commands separated by semicolons.
9037 most common commands are:
9043 to restore default color
9055 for black foreground
9061 for green foreground
9064 for yellow (or brown) foreground
9070 for purple foreground
9076 for white (or gray) foreground
9079 for black background
9085 for green background
9088 for yellow (or brown) background
9094 for purple background
9100 for white (or gray) background
9104 Not all commands will work on all systems or display devices.
9106 A few terminal programs do not recognize the default end code
9108 If all text gets colorized after you do a directory
9109 listing, try changing the
9114 numerical codes for your standard fore- and background colors.
9118 The machine type (microprocessor class or machine model), as determined at compile time.
9121 If set, printable characters are not rebound to
9122 .Va self-insert-command
9124 .Va Native Language System support
9127 The operating system, as determined at compile time.
9130 A colon-separated list of directories in which to look for executables.
9133 shell variable, but in a different format.
9138 shell variable, but not synchronized to it;
9139 updated only after an actual directory change.
9141 .B REMOTEHOST \fR(+)
9142 The host from which the user has logged in remotely, if this is the case and
9143 the shell is able to determine it.
9144 Set only if the shell was so compiled;
9155 The current system type.
9164 The terminal capability string.
9166 .Va Terminal management
9174 The vendor, as determined at compile time.
9177 The pathname to a default full-screen editor.
9180 editor command if the
9183 shell variable is unset.
9186 environment variable.
9191 Read first by every shell.
9192 ConvexOS, Stellix and Intel use
9197 A/UX, AMIX, Cray and IRIX have no equivalent in
9200 but read this file in
9203 Solaris 2.x does not have it either, but
9210 Read by login shells after
9212 ConvexOS, Stellix and Intel use
9220 A/UX, AMIX, Cray and IRIX use
9224 Read by every shell after
9229 Read by every shell, if
9248 Read by login shells after
9252 is set, but see also
9256 Read by login shells after
9260 The shell may be compiled to read
9262 before instead of after
9270 .I ~/.cshdirs \fR(+)
9271 Read by login shells after
9275 is set, but see also
9279 Read by login shells at logout.
9280 ConvexOS, Stellix and Intel use
9285 A/UX, AMIX, Cray and IRIX have no equivalent in
9288 but read this file in
9291 Solaris 2.x does not have it either, but
9298 Read by login shells at logout after
9303 Used to interpret shell scripts not starting with a
9311 Source of home directories for
9316 The order in which startup files are read may differ if the shell was so
9318 .Va Startup and shutdown
9322 .Sh "NEW FEATURES (+)"
9323 This manual describes
9328 users will want to pay special attention to
9332 A command-line editor, which supports
9337 (1)\-style key bindings.
9339 .Va The command-line editor
9343 Programmable, interactive word completion and listing.
9345 .Sx Completion and listing
9352 .Va Spelling correction
9353 (q.v.) of filenames, commands and variables.
9356 (q.v.) which perform other useful functions in the middle of
9357 typed commands, including documentation lookup
9359 quick editor restarting
9360 .Va ( run-fg-editor )
9363 .Va ( which-command ).
9365 An enhanced history mechanism.
9366 Events in the history list are time-stamped.
9369 command and its associated shell variables,
9370 the previously undocumented
9372 event specifier and new modifiers
9374 .Va History substitution
9379 .Va history-search-*
9385 .Va toggle-literal-history
9391 Enhanced directory parsing and directory stack handling.
9400 commands and their associated
9401 shell variables, the description of
9402 .Va Directory stack substitution
9412 .Va normalize-command
9417 Negation in glob-patterns.
9419 .Va Filename substitution
9422 .Va File inquiry operators
9425 builtin which uses them.
9428 .Va Automatic, periodic and timed events
9430 scheduled events, special aliases, automatic logout and terminal locking,
9431 command timing and watching for logins and logouts.
9433 Support for the Native Language System
9435 .Va Native Language System support
9439 .Va OS variant support
9443 and system-dependent file locations (see
9447 Extensive terminal-management capabilities.
9449 .Va Terminal management
9451 New builtin commands including
9465 New variables that make useful information easily available to the shell.
9482 shell variables and the
9495 A new syntax for including useful information in the prompt string
9499 and special prompts for loops and spelling correction
9506 Read-only variables.
9508 .Va Variable substitution
9510 When a suspended command is restarted, the shell prints the directory
9511 it started in if this is different from the current directory.
9513 be misleading (i.e., wrong) as the job may have changed directories internally.
9515 Shell builtin functions are not stoppable/restartable.
9519 are also not handled gracefully when stopping is
9523 , the shell will then immediately execute
9525 This is especially noticeable if this expansion results from an
9527 It suffices to place the sequence of commands in ()'s to force it
9528 to a subshell, i.e.,
9531 Control over tty output after processes are started is primitive; perhaps
9532 this will inspire someone to work on a good virtual terminal interface.
9533 In a virtual terminal interface much more interesting things could be
9534 done with output control.
9536 Alias substitution is most often used to clumsily simulate shell procedures;
9537 shell procedures should be provided rather than aliases.
9539 Control structures should be parsed rather than being recognized as
9541 This would allow control commands to be placed anywhere,
9544 , and to be used with
9551 doesn't ignore here documents when looking for its
9554 It should be possible to use the
9556 modifiers on the output of command
9559 The screen update for lines longer than the screen width is very poor
9560 if the terminal cannot move the cursor up (i.e., terminal type
9567 don't need to be environment variables.
9569 Glob-patterns which do not use
9579 are not negated correctly.
9581 The single-command form of
9583 does output redirection even if
9584 the expression is false and the command is not executed.
9586 \fIls\-F\fR includes file identification characters when sorting filenames
9587 and does not handle control characters in filenames well.
9591 Command substitution supports multiple commands and conditions, but not
9596 Report bugs at https://bugs.astron.com/, preferably with fixes.
9598 help maintain and test tcsh, add yourself to the mailing list in
9599 https://mailman.astron.com/.
9601 on a line by itself in the body.
9603 In 1964, DEC produced the PDP-6.
9604 The PDP-10 was a later re-implementation.
9606 was re-christened the DECsystem-10 in 1970 or so when DEC brought out the
9607 second model, the KI10.
9609 TENEX was created at Bolt, Beranek & Newman (a Cambridge, Massachusetts
9611 1972 as an experiment in demand-paged virtual memory operating systems.
9613 built a new pager for the DEC PDP-10 and created the OS to go with it.
9615 extremely successful in academia.
9617 In 1975, DEC brought out a new model of the PDP-10, the KL10; they intended to
9618 have only a version of TENEX, which they had licensed from BBN, for the new
9620 They called their version TOPS-20 (their capitalization is trademarked).
9621 A lot of TOPS-10 users (`The OPerating System for PDP-10') objected; thus DEC
9622 found themselves supporting two incompatible systems on the same hardware--but
9623 then there were 6 on the PDP-11!
9625 TENEX, and TOPS-20 to version 3, had command completion
9626 via a user-code-level subroutine library called ULTCMD.
9628 moved all that capability and more into the monitor (`kernel' for you Unix
9629 types), accessed by the COMND% JSYS (`Jump to SYStem' instruction, the
9630 supervisor call mechanism [are my IBM roots also showing?]).
9632 The creator of tcsh was impressed by this feature and several others of TENEX
9633 and TOPS-20, and created a version of csh which mimicked them.
9635 The system limits argument lists to ARG_MAX characters.
9637 The number of arguments to a command which involves filename expansion is
9638 limited to 1/6th the number of characters allowed in an argument list.
9640 Command substitutions may substitute no more characters than are allowed in
9643 To detect looping, the shell restricts the number of
9645 substitutions on a single line to 20.
9647 csh(1), emacs(1), ls(1), newgrp(1), sh(1), setpath(1), stty(1), su(1),
9648 tset(1), vi(1), x(1), access(2), execve(2), fork(2), killpg(2),
9649 pipe(2), setrlimit(2), sigvec(2), stat(2), umask(2), vfork(2), wait(2),
9650 malloc(3), setlocale(3), tty(4), a.out(5), termcap(5), environ(7),
9651 termio(7), Introduction to the C Shell
9653 This manual documents tcsh 6.21.00 (Astron) 2019-05-08.
9661 J.E. Kulp, IIASA, Laxenburg, Austria
9662 Job control and directory stack features
9664 Ken Greer, HP Labs, 1981
9665 File name completion
9667 Mike Ellis, Fairchild, 1983
9668 Command name recognition/completion
9670 Paul Placeway, Ohio State CIS Dept., 1983-1993
9671 Command line editor, prompt routines, new glob syntax and numerous fixes
9674 Karl Kleinpaste, CCI 1983-4
9675 Special aliases, directory stack extraction stuff, login/logout watch,
9676 scheduled events, and the idea of the new prompt format
9678 Rayan Zachariassen, University of Toronto, 1984
9681 builtins and numerous bug fixes, modifications
9684 Chris Kingsley, Caltech
9685 Fast storage allocator routines
9687 Chris Grevstad, TRW, 1987
9693 Christos S. Zoulas, Cornell U. EE Dept., 1987-94
9694 Ports to HPUX, SVR2 and SVR3, a SysV version of getwd.c, SHORT_STRINGS support
9695 and a new version of sh.glob.c
9697 James J Dempsey, BBN, and Paul Placeway, OSU, 1988
9700 Daniel Long, NNSC, 1988
9703 Patrick Wolfe, Kuck and Associates, Inc., 1988
9707 David C Lawrence, Rensselaer Polytechnic Institute, 1989
9709 and ambiguous completion listing
9711 Alec Wolman, DEC, 1989
9712 Newlines in the prompt
9714 Matt Landau, BBN, 1989
9717 Ray Moody, Purdue Physics, 1989
9718 Magic space bar history expansion
9720 Mordechai ????, Intel, 1989
9721 printprompt() fixes and additions
9723 Kazuhiro Honda, Dept. of Computer Science, Keio University, 1989
9724 Automatic spelling correction and
9727 Per Hedeland, Ellemtel, Sweden, 1990-
9728 Various bugfixes, improvements and manual updates
9730 Hans J. Albertsson (Sun Sweden)
9738 Interrupt handling fixes
9740 Michael Fine, Digital Equipment Corp
9741 Extended key support
9743 Eric Schnoebelen, Convex, 1990
9744 Convex support, lots of
9747 save and restore of directory stack
9749 Ron Flax, Apple, 1990
9752 Dan Oscarsson, LTH Sweden, 1990
9753 NLS support and simulated NLS support for non NLS sites, fixes
9755 Johan Widen, SICS Sweden, 1990
9761 Matt Day, Sanyo Icon, 1990
9762 POSIX termio support, SysV limit fixes
9764 Jaap Vermeulen, Sequent, 1990-91
9765 Vi mode fixes, expand-line, window change fixes, Symmetry port
9767 Martin Boyer, Institut de recherche d'Hydro-Quebec, 1991
9769 beeping options, modified the history search to search for
9770 the whole string from the beginning of the line to the cursor.
9772 Scott Krotz, Motorola, 1991
9775 David Dawes, Sydney U. Australia, Physics Dept., 1991
9776 SVR4 job control fixes
9778 Jose Sousa, Interactive Systems Corp., 1991
9785 Marc Horowitz, MIT, 1991
9786 ANSIfication fixes, new exec hashing code, imake fixes,
9789 Bruce Sterling Woodcock, sterling@netcom.com, 1991-1995
9790 ETA and Pyramid port, Makefile and lint fixes,
9793 various other portability changes and bug fixes
9796 .Va complete-word-fwd
9798 .Va complete-word-back
9800 Harry C. Pulley, 1992
9803 Andy Phillips, Mullard Space Science Lab U.K., 1992
9806 Beto Appleton, IBM Corp., 1992
9807 Walking process group fixes,
9810 POSIX file tests, POSIX SIGHUP
9812 Scott Bolte, Cray Computer Corp., 1992
9815 Kaveh R. Ghazi, Rutgers University, 1992
9816 Tek, m88k, Titan and Masscomp ports and fixes.
9817 Added autoconf support.
9819 Mark Linderman, Cornell University, 1992
9822 Mika Liljeberg, liljeber@kruuna.Helsinki.FI, 1992
9825 Tim P. Starrin, NASA Langley Research Center Operations, 1993
9828 Dave Schweisguth, Yale University, 1993-4
9829 New man page and tcsh.man2html
9831 Larry Schwimmer, Stanford University, 1993
9832 AFS and HESIOD patches
9834 Luke Mewburn, RMIT University, 1994-6
9835 Enhanced directory printing in prompt,
9841 Edward Hutchins, Silicon Graphics Inc., 1996
9844 Martin Kraemer, 1997
9845 Ported to Siemens Nixdorf EBCDIC machine
9847 Amol Deshpande, Microsoft, 1997
9848 Ported to WIN32 (Windows/95 and Windows/NT); wrote all the missing library
9849 and message catalog code to interface to Windows.
9856 Bryan Dunlap, Clayton Elwell, Karl Kleinpaste, Bob Manson, Steve Romig,
9857 Diana Smetters, Bob Sutterfield, Mark Verber, Elizabeth Zwicky and all
9858 the other people at Ohio State for suggestions and encouragement
9860 All the people on the net, for putting up with,
9861 reporting bugs in, and suggesting new additions to each and every version
9863 Richard M. Alderson III, for writing the