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 .Ss 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
687 completion 1) ignores case and 2) considers periods, hyphens and underscores
692 to be word separators and hyphens and underscores to be equivalent.
693 If you had the following files
694 .Bd -literal -offset indent
695 comp.lang.c comp.lang.perl comp.std.c++
696 comp.lang.c++ comp.std.c
700 .Sq mail \-f c.l.c[tab] ,
701 it would be completed to
702 .Sq mail \-f comp.lang.c ,
709 .Sq mail \-f c..c++[^D]
716 in the following directory
717 .Bd -literal -offset indent
718 A_silly_file a-hyphenated-file another_silly_file
721 would list all three files, because case is ignored and hyphens and
722 underscores are equivalent.
723 Periods, however, are not equivalent to
724 hyphens or underscores.
728 shell variable is set to
731 ignores case and differences between a hyphen and an underscore word
732 separator only when the user types a lowercase character or a hyphen.
733 Entering an uppercase character or an underscore will not match the
734 corresponding lowercase character or hyphen word separator.
737 in the directory of the previous example would
738 still list all three files, but typing
747 .Sq another_silly_file
748 because the user explicitly used an uppercase
749 or an underscore character.
751 Completion and listing are affected by several other shell variables:
753 can be set to complete on the shortest possible unique
754 match, even if more typing might result in a longer match:
755 .Bd -literal -offset indent
757 fodder foo food foonly
768 but if we type another
770 .Bd -literal -offset indent
775 the completion completes on
783 can be set to run the
786 before each completion attempt,
789 spelling-correct the word to be completed (see
790 .Sx Spelling correction )
791 before each completion attempt and
793 can be set to complete commands automatically after one hits
796 can be set to make completion beep or not beep in a variety
799 can be set to never beep at all.
801 can be set to a list of directories and/or patterns that
802 match directories to prevent the completion mechanism from
809 can be set to limit the number of items
810 and rows (respectively) that are listed without asking first.
811 .Va recognize_only_executables
812 can be set to make the shell list only
813 executables when listing commands, but it is quite slow.
817 builtin command can be used to tell the shell how
818 to complete words other than filenames, commands and variables.
819 Completion and listing do not work on glob-patterns (see
820 .Sx Filename substitution ) ,
825 editor commands perform
826 equivalent functions for glob-patterns.
827 .Ss Spelling correction (+)
828 The shell can sometimes correct the spelling of filenames, commands and
829 variable names as well as completing and listing them.
831 Individual words can be spelling-corrected with the
833 editor command (usually bound to M-s and M-S)
834 and the entire input buffer with
836 (usually bound to M-$).
839 shell variable can be set to
841 to correct the command name or
843 to correct the entire line each time return is typed, and
845 can be set to correct the word to be completed
846 before each completion attempt.
848 When spelling correction is invoked in any of these ways and
849 the shell thinks that any part of the command line is misspelled,
850 it prompts with the corrected line:
851 .Bd -literal -offset indent
854 CORRECT>ls /usr/bin (y|n|e|a)?
859 or space to execute the corrected line,
861 to leave the uncorrected command in the input buffer,
863 to abort the command as if
866 anything else to execute the original line unchanged.
868 Spelling correction recognizes user-defined completions (see the
871 If an input word in a position for
872 which a completion is defined resembles a word in the completion list,
873 spelling correction registers a misspelling and suggests the latter
874 word as a correction.
875 However, if the input word does not match any of
876 the possible completions for that position, spelling correction does
877 not register a misspelling.
879 Like completion, spelling correction works anywhere in the line,
880 pushing the rest of the line to the right and possibly leaving
881 extra characters to the right of the cursor.
882 .Ss Editor commands (+)
884 lists key bindings and
886 lists and briefly describes editor commands.
887 Only new or especially interesting editor commands are described here.
892 for descriptions of each editor's key bindings.
894 The character or characters to which each command is bound by default is
895 given in parentheses.
897 means a control character and
899 a meta character, typed as
901 on terminals without a meta key.
902 Case counts, but commands that are bound
903 to letters by default are bound to both lower- and uppercase letters for
905 .Bl -tag -width indent
906 .It Ic backward-char Ar (^B, left)
907 Move back a character.
908 Cursor behavior modified by
910 .It Ic backward-delete-word Ar (M-^H, M-^?)
911 Cut from beginning of current word to cursor \- saved in cut buffer.
912 Word boundary behavior modified by
914 .It Ic backward-word Ar (M-b, M-B)
915 Move to beginning of current word.
916 Word boundary and cursor behavior modified by
918 .It Ic beginning-of-line Ar (^A, home)
919 Move to beginning of line.
920 Cursor behavior modified by
922 .It Ic capitalize-word Ar (M-c, M-C)
923 Capitalize the characters from cursor to end of current word.
924 Word boundary behavior modified by
926 .It Ic complete-word Ar (tab)
927 Completes a word as described under
928 .Sx Completion and listing
929 .It Ic complete-word-back Ar (not bound)
931 .Ic complete-word-fwd ,
932 but steps up from the end of the list.
933 .It Ic complete-word-fwd Ar (not bound)
934 Replaces the current word with the first word in the list of possible
936 May be repeated to step down through the list.
937 At the end of the list, beeps and reverts to the incomplete word.
938 .It Ic complete-word-raw Ar (^X-tab)
941 but ignores user-defined completions.
942 .It Ic copy-prev-word Ar (M-^_)
943 Copies the previous word in the current line into the input buffer.
946 Word boundary behavior modified by
948 .It Ic dabbrev-expand Ar (M-/)
949 Expands the current word to the most recent preceding one for which
950 the current is a leading substring, wrapping around the history list
954 without any intervening typing
955 changes to the next previous word etc., skipping identical matches
957 .Ic history-search-backward
959 .It Ic delete-char Ar (not bound)
960 Deletes the character under the cursor.
962 .Ic delete-char-or-list-or-eof
963 Cursor behavior modified by
965 .It Ic delete-char-or-eof Ar (not bound)
968 if there is a character under the cursor or
972 .Ic delete-char-or-list-or-eof
973 Cursor behavior modified by
975 .It Ic delete-char-or-list Ar (not bound)
978 if there is a character under the cursor
981 at the end of the line.
983 .Ic delete-char-or-list-or-eof
984 .It Ic delete-char-or-list-or-eof Ar (^D)
987 if there is a character under the cursor,
989 at the end of the line or
992 See also those three commands, each of which does only a single action, and
993 .Ic delete-char-or-eof ,
994 .Ic delete-char-or-list
997 each of which does a different two out of the three.
998 .It Ic delete-word Ar (M-d, M-D)
999 Cut from cursor to end of current word \- save in cut buffer.
1000 Word boundary behavior modified by
1002 .It Ic down-history Ar (down-arrow, ^N)
1005 but steps down, stopping at the original input line.
1006 .It Ic downcase-word Ar (M-l, M-L)
1007 Lowercase the characters from cursor to end of current word.
1008 Word boundary behavior modified by
1010 .It Ic end-of-file Ar (not bound)
1011 Signals an end of file, causing the shell to exit unless the
1013 shell variable (q.v.) is set to prevent this.
1015 .Ic delete-char-or-list-or-eof
1016 .It Ic end-of-line Ar (^E, end)
1017 Move cursor to end of line.
1018 Cursor behavior modified by
1020 .It Ic expand-history Ar (M-space)
1021 Expands history substitutions in the current word.
1023 .Sx History substitution
1026 .Ic toggle-literal-history
1030 .It Ic expand-glob Ar (^X-*)
1031 Expands the glob-pattern to the left of the cursor.
1033 .Sx Filename substitution
1034 .It Ic expand-line Ar (not bound)
1036 .Ic expand-history ,
1037 but expands history substitutions in each word in the input buffer.
1038 .It Ic expand-variables Ar (^X-$)
1039 Expands the variable to the left of the cursor.
1041 .Sx Variable substitution
1042 .It Ic forward-char Ar (^F, right)
1043 Move forward one character.
1044 Cursor behavior modified by
1046 .It Ic forward-word Ar (M-f, M-F)
1047 Move forward to end of current word.
1048 Word boundary and cursor behavior modified by
1050 .It Ic history-search-backward Ar (M-p, M-P)
1051 Searches backwards through the history list for a command beginning with
1052 the current contents of the input buffer up to the cursor and copies it
1053 into the input buffer.
1054 The search string may be a glob-pattern (see
1055 .Sx Filename substitution )
1065 will proceed from the
1066 appropriate point in the history list.
1069 .Ic history-search-forward
1072 .It Ic history-search-forward Ar (M-n, M-N)
1074 .Ic history-search-backward ,
1075 but searches forward.
1076 .It Ic i-search-back Ar (not bound)
1077 Searches backward like
1078 .Ic history-search-backward ,
1079 copies the first match
1080 into the input buffer with the cursor positioned at the end of the pattern,
1083 and the first match.
1084 Additional characters may be
1085 typed to extend the search,
1087 may be typed to continue
1088 searching with the same pattern, wrapping around the history list if
1092 single character for this to work) or one of the following special characters
1095 .Bl -tag -width indent -compact
1097 Appends the rest of the word under the cursor to the search pattern.
1099 (or any character bound to
1100 .Ic backward-delete-char )
1101 Undoes the effect of the last character typed and deletes a character
1102 from the search pattern if appropriate.
1104 If the previous search was successful, aborts the entire search.
1105 If not, goes back to the last successful search.
1107 Ends the search, leaving the current line in the input buffer.
1110 Any other character not bound to
1111 .Ic self-insert-command
1113 search, leaving the current line in the input buffer, and
1114 is then interpreted as normal input.
1115 In particular, a carriage return
1116 causes the current line to be executed.
1120 .Ic history-search-backward
1121 Word boundary behavior modified by
1123 .It Ic i-search-fwd Ar (not bound)
1126 but searches forward.
1127 Word boundary behavior modified by
1129 .It Ic insert-last-word Ar (M-_)
1130 Inserts the last word of the previous input line
1132 into the input buffer.
1135 .It Ic list-choices Ar (M-^D)
1136 Lists completion possibilities as described under
1137 .Sx Completion and listing
1139 .Ic delete-char-or-list-or-eof
1141 .Ic list-choices-raw
1142 .It Ic list-choices-raw Ar (^X-^D)
1145 but ignores user-defined completions.
1146 .It Ic list-glob Ar (^X-g, ^X-G)
1149 builtin) matches to the glob-pattern
1151 .Sx Filename substitution )
1152 to the left of the cursor.
1153 .It Ic list-or-eof Ar (not bound)
1160 .Ic delete-char-or-list-or-eof
1161 .It Ic magic-space Ar (not bound)
1162 Expands history substitutions in the current line,
1164 .Ic expand-history ,
1165 and inserts a space.
1167 is designed to be bound to the space bar,
1168 but is not bound by default.
1169 .It Ic normalize-command Ar (^X-?)
1170 Searches for the current word in PATH and, if it is found, replaces it with
1171 the full path to the executable.
1172 Special characters are quoted.
1174 expanded and quoted but commands within aliases are not.
1176 useful with commands that take commands as arguments, e.g.,
1180 .It Ic normalize-path Ar (^X-n, ^X-N)
1181 Expands the current word as described under the
1187 .It Ic overwrite-mode Ar (unbound)
1188 Toggles between input and overwrite modes.
1189 .It Ic run-fg-editor Ar (M-^Z)
1190 Saves the current input line and
1191 looks for a stopped job where the file name portion of its first word
1197 is not set, then the file name portion of the
1199 environment variable
1204 environment variable
1208 If such a job is found, it is restarted as if
1212 This is used to toggle back and forth between an editor and
1214 Some people bind this command to
1217 can do this even more easily.
1218 .It Ic run-help Ar (M-h, M-H)
1219 Searches for documentation on the current command, using the same notion of
1221 as the completion routines, and prints it.
1225 is designed for short help files.
1226 If the special alias
1228 is defined, it is run with the
1229 command name as a sole argument.
1231 documentation should be in a file named
1238 which should be in one
1239 of the directories listed in the
1241 environment variable.
1242 If there is more than one help file only the first is printed.
1243 .It Ic self-insert-command Ar (text characters)
1244 In insert mode (the default), inserts the typed character into the input line after the character under the cursor.
1245 In overwrite mode, replaces the character under the cursor with the typed character.
1246 The input mode is normally preserved between lines, but the
1248 shell variable can be set to
1253 editor in that mode at the beginning of each line.
1256 .It Ic sequence-lead-in Ar (arrow prefix, meta prefix, ^X)
1257 Indicates that the following characters are part of a
1259 Binding a command to a multi-key sequence really creates
1260 two bindings: the first character to
1261 .Ic sequence-lead-in
1263 whole sequence to the command.
1264 All sequences beginning with a character
1266 .Ic sequence-lead-in
1267 are effectively bound to
1269 unless bound to another command.
1270 .It Ic spell-line Ar (M-$)
1271 Attempts to correct the spelling of each word in the input buffer, like
1273 but ignores words whose first character is one of
1284 to avoid problems with switches, substitutions and the like.
1286 .Sx Spelling correction
1287 .It Ic spell-word Ar (M-s, M-S)
1288 Attempts to correct the spelling of the current word as described under
1289 .Sx Spelling correction
1290 Checks each component of a word which appears to be a pathname.
1291 .It Ic toggle-literal-history Ar (M-r, M-R)
1294 history substitutions in the input buffer.
1300 .It Ic undefined-key Ar (any unbound key)
1302 .It Ic up-history Ar (up-arrow, ^P)
1303 Copies the previous entry in the history list into the input buffer.
1306 is set, uses the literal form of the entry.
1307 May be repeated to step up through the history list, stopping at the top.
1308 .It Ic upcase-word Ar (M-u, M-U)
1309 Uppercase the characters from cursor to end of current word.
1310 Word boundary behavior modified by
1312 .It Ic vi-beginning-of-next-word Ar (not bound)
1313 Vi goto the beginning of next word.
1314 Word boundary and cursor behavior modified by
1316 .It Ic vi-eword Ar (not bound)
1317 Vi move to the end of the current word.
1318 Word boundary behavior modified by
1320 .It Ic vi-search-back Ar (?)
1323 for a search string (which may be a glob-pattern, as with
1324 .Ic history-search-backward ),
1325 searches for it and copies it into the input buffer.
1326 The bell rings if no match is found.
1327 Hitting return ends the search and leaves the last match in the input
1329 Hitting escape ends the search and executes the match.
1332 .It Ic vi-search-fwd Ar (/)
1334 .Ic vi-search-back ,
1335 but searches forward.
1336 .It Ic which-command Ar (M-?)
1339 (see the description of the builtin command) on the
1340 first word of the input buffer.
1341 .It Ic yank-pop Ar (M-y)
1342 When executed immediately after a
1346 replaces the yanked string with the next previous string from the
1347 killring. This also has the effect of rotating the killring, such that
1348 this string will be considered the most recently killed by a later
1352 will cycle through the
1353 killring any number of times.
1355 .Ss Lexical structure
1356 The shell splits input lines into words at blanks and tabs.
1367 and the doubled characters
1373 are always separate words, whether or not they are
1374 surrounded by whitespace.
1376 When the shell's input is not a terminal, the character
1382 and the rest of the input line on which it appears is
1383 discarded before further parsing.
1385 A special character (including a blank or tab) may be prevented from having
1386 its special meaning, and possibly made part of another word, by preceding it
1389 or enclosing it in single
1397 When not otherwise quoted a newline preceded by a
1399 is equivalent to a blank, but inside quotes this sequence results in a
1405 .Sx History substitution
1406 can be prevented by enclosing the strings (or parts of strings)
1407 in which they appear with single quotes or by quoting the crucial character(s)
1413 .Sx Variable substitution
1415 .Sx Command substitution
1419 .Sx ( Alias substitution
1420 is no exception: quoting in any way any
1421 character of a word for which an
1423 has been defined prevents
1424 substitution of the alias.
1425 The usual way of quoting an alias is to precede it
1427 .Sx History substitution
1429 backslashes but not by single quotes.
1430 Strings quoted with double or backward
1432 .Sx Variable substitution
1434 .Sx Command substitution ,
1435 but other substitutions are prevented.
1437 Text inside single or double quotes becomes a single word (or part of one).
1438 Metacharacters in these strings, including blanks and tabs, do not form
1440 Only in one special case (see
1441 .Sx Command substitution
1442 below) can a double-quoted string yield parts of more than one word;
1443 single-quoted strings never do.
1444 Backward quotes are special: they signal
1445 .Sx Command substitution
1446 (q.v.), which may result in more than one word.
1448 Quoting complex strings, particularly strings which themselves contain quoting
1449 characters, can be confusing.
1450 Remember that quotes need not be used as they are
1452 It may be easier to quote not an entire string, but only
1453 those parts of the string which need quoting, using different types of quoting
1454 to do so if appropriate.
1458 shell variable (q.v.) can be set to make backslashes
1464 (+) This may make complex quoting tasks
1465 easier, but it can cause syntax errors in
1469 We now describe the various transformations the shell performs on the input in
1470 the order in which they occur.
1471 We note in passing the data structures involved
1472 and the commands and variables which affect them.
1473 Remember that substitutions
1474 can be prevented by quoting as described under
1475 .Sx Lexical structure .
1476 .Ss History substitution
1479 input from the terminal is saved in the history list.
1480 The previous command is always saved, and the
1483 variable can be set to a number to save that many commands.
1486 shell variable can be set to not save duplicate events or consecutive duplicate
1489 Saved commands are numbered sequentially from 1 and stamped with the time.
1490 It is not usually necessary to use event numbers, but the current event number
1491 can be made part of the prompt by placing an
1497 The shell actually saves history in expanded and literal (unexpanded) forms.
1500 shell variable is set, commands that display and store
1501 history use the literal form.
1505 builtin command can print, store in a file, restore
1506 and clear the history list at any time,
1511 shell variables can be set to
1512 store the history list automatically on logout and restore it on login.
1514 History substitutions introduce words from the history list into the input
1515 stream, making it easy to repeat commands, repeat arguments of a previous
1516 command in the current command, or fix spelling mistakes in the previous
1517 command with little typing and a high degree of confidence.
1519 History substitutions begin with the character
1521 They may begin anywhere in
1522 the input stream, but they do not nest.
1525 may be preceded by a
1528 prevent its special meaning; for convenience, a
1530 is passed unchanged when it
1531 is followed by a blank, tab, newline,
1535 History substitutions also
1536 occur when an input line begins with
1538 This special abbreviation will be
1540 The characters used to signal history substitution
1544 can be changed by setting the
1548 line which contains a history substitution is printed before it is executed.
1550 A history substitution may have an
1551 .Sq event specification ,
1552 which indicates the event from which words are to be taken, a
1553 .Sq word designator ,
1554 which selects particular words from the chosen event, and/or a
1556 which manipulates the selected words.
1558 An event specification can be
1560 .Bl -tag -width XXXX -offset indent -compact
1562 A number, referring to a particular event
1564 An offset, referring to the event
1566 before the current event
1569 This should be used carefully in
1571 where there is no check for recursion.
1573 allows 10 levels of recursion.
1576 The previous event (equivalent to
1579 The most recent event whose first word begins with the string
1582 The most recent event which contains the string
1586 can be omitted if it is immediately followed by a newline.
1589 For example, consider this bit of someone's history list:
1590 .Bd -literal -offset indent
1591 9 8:30 nroff \-man wumpus.man
1592 10 8:31 cp wumpus.man wumpus.man.old
1593 11 8:36 vi wumpus.man
1594 12 8:37 diff wumpus.man.old wumpus.man
1597 The commands are shown with their event numbers and time stamps.
1598 The current event, which we haven't typed in yet, is event 13.
1604 refers to the previous event, 12.
1612 is described below).
1614 refers to event 9, which begins with
1617 also refers to event 12, which contains
1619 Without word designators or modifiers history references simply expand to the
1620 entire event, so we might type
1622 to redo the copy command or
1626 output scrolled off the top of the screen.
1628 History references may be insulated from the surrounding text with braces if
1632 would look for a command beginning with
1634 and, in this example, not find one, but
1638 .Sq vi wumpus.mandoc
1639 Even in braces, history substitutions do not nest.
1643 expands, for example,
1650 expands it to the last event beginning
1653 only completely numeric arguments are treated as event numbers.
1654 This makes it possible to recall events beginning with numbers.
1662 To select words from an event we can follow the event specification by a
1664 and a designator for the desired words.
1665 The words of an input line are
1666 numbered from 0, the first (usually command) word being 0, the second word
1667 (first argument) being 1, etc.
1668 The basic word designators are:
1670 .Bl -tag -width XXXX -offset indent -compact
1672 The first (command) word
1678 The first argument, equivalent to
1683 The word matched by an ?
1694 but returns nothing if the event contains only 1 word
1701 but omitting the last word
1705 Selected words are inserted into the command line separated by single blanks.
1708 command in the previous example might have been
1710 .Sq diff !!:1.old !!:1
1713 to select the first argument
1714 from the previous event) or
1715 .Sq diff !\-2:2 !\-2:1
1716 to select and swap the
1720 If we didn't care about the order of the
1721 `diff' we might have said
1727 command might have been written
1728 .Sq cp wumpus.man !#:1.old
1731 to refer to the current event.
1732 `!n:\- hurkle.man' would reuse the first two words from the
1736 .Sq nroff \-man hurkle.man
1740 separating the event specification from the word designator can be
1741 omitted if the argument selector begins with a
1750 command might have been
1751 .Sq diff !!^.old !!^
1754 .Sq diff !!$.old !!$
1760 an argument selector beginning with
1762 will be interpreted as an event
1765 A history reference may have a word designator but no event specification.
1766 It then references the previous command.
1769 example, we could have said simply `diff
1770 !^.old !^' or, to get the arguments in the opposite order, just
1773 The word or words in a history reference can be edited, or
1776 by following it with one or more modifiers, each preceded by a
1779 .Bl -tag -width XXXXXX -offset indent -compact
1781 Remove a trailing pathname component, leaving the head.
1783 Remove all leading pathname components, leaving the tail.
1785 Remove a filename extension
1787 leaving the root name.
1789 Remove all but the extension.
1791 Uppercase the first lowercase letter.
1793 Lowercase the first uppercase letter.
1800 is simply a string like
1802 , not a regular expression as in
1806 Any character may be used as the delimiter in place of
1810 can be used to quote the delimiter inside
1829 from a previous substitution or the
1831 from a previous search or event number in event specification is used.
1832 The trailing delimiter may be omitted if it is immediately followed by a
1835 Repeat the previous substitution.
1837 Apply the following modifier once to each word.
1839 Apply the following modifier as many times as possible to a single word.
1843 can be used together to apply a modifier globally.
1846 modifier, only the patterns contained in the original word are
1847 substituted, not patterns that contain any substitution result.
1849 Print the new command line but do not execute it.
1851 Quote the substituted words, preventing further substitutions.
1855 but break into words at blanks, tabs and newlines.
1858 Modifiers are applied to only the first modifiable word (unless
1861 It is an error for no word to be modifiable.
1865 command might have been written as `diff wumpus.man.old
1870 from the first argument on the same line
1873 .Sq echo hello out there
1879 to say it out loud, or
1883 .Sq mail \-s "I forgot my password" rot
1887 correct the spelling of
1890 .Sx Spelling correction
1892 different approach).
1894 There is a special abbreviation for substitutions.
1896 when it is the first character on an input line, is equivalent to
1898 Thus we might have said
1900 to make the spelling correction in the
1902 This is the only history substitution which does not explicitly begin with
1907 as such, only one modifier may be applied to each history
1908 or variable expansion.
1911 more than one may be used, for example
1912 .Bd -literal -offset indent
1913 % mv wumpus.man /usr/man/man1/wumpus.1
1922 A substitution followed by a
1923 colon may need to be insulated from it with braces:
1924 .Bd -literal -offset indent
1925 > mv a.out /usr/games/wumpus
1926 > setenv PATH !$:h:$PATH
1928 > setenv PATH !{\-2$:h}:$PATH
1929 setenv PATH /usr/games:/bin:/usr/bin:.
1932 The first attempt would succeed in
1938 expects another modifier after the second colon
1942 Finally, history can be accessed through the editor as well as through
1943 the substitutions just described.
1948 .Ic history-search-backward
1959 .Ic insert-last-word
1960 editor commands search for
1961 events in the history list and copy them into the input buffer.
1963 .Ic toggle-literal-history
1964 editor command switches between the
1965 expanded and literal forms of history lines in the input buffer.
1969 expand history substitutions
1970 in the current word and in the entire input buffer respectively.
1971 .Ss Alias substitution
1972 The shell maintains a list of aliases which can be set, unset and printed by
1978 After a command line is parsed
1979 into simple commands (see
1981 the first word of each command,
1982 left-to-right, is checked to see if it has an alias.
1983 If so, the first word is
1984 replaced by the alias.
1985 If the alias contains a history reference, it undergoes
1986 .Va History substitution
1987 (q.v.) as though the original command were the
1988 previous input line.
1989 If the alias does not contain a history reference, the
1990 argument list is left untouched.
1992 Thus if the alias for
1999 \-l /usr', the argument list here being undisturbed.
2003 .Sq grep !/etc/passwd
2006 would become `grep bill
2008 Aliases can be used to introduce parser metasyntax.
2012 pr \e!* | lpr'' defines a
2016 (1)s its arguments to the line printer.
2018 Alias substitution is repeated until the first word of the command has no
2020 If an alias substitution does not change the first word (as in the
2021 previous example) it is flagged to prevent a loop.
2022 Other loops are detected and
2025 Some aliases are referred to by the shell; see
2027 .Ss Variable substitution
2028 The shell maintains a list of variables, each of which has as value a list of
2030 The values of shell variables can be displayed and changed with the
2035 The system maintains its own list of
2038 These can be displayed and changed with
2045 (+) Variables may be made read-only with
2048 Read-only variables may not be modified or unset;
2049 attempting to do so will cause an error.
2050 Once made read-only, a variable cannot be made writable,
2053 should be used with caution.
2054 Environment variables cannot be made read-only.
2056 Some variables are set by the shell or referred to by it.
2059 variable is an image of the shell's argument
2060 list, and words of this variable's value are referred to in special ways.
2061 Some of the variables referred to by the shell are toggles;
2062 the shell does not care what their value is, only whether they are set or not.
2065 variable is a toggle which causes command
2068 .Fl v\fR command line option sets this variable.
2069 .Va Special shell variables
2070 lists all variables which are referred to by the shell.
2072 Other operations treat variables numerically.
2075 command permits numeric
2076 calculations to be performed and the result assigned to a variable.
2078 values are, however, always represented as (zero or more) strings.
2080 purposes of numeric operations, the null string is considered to be zero, and
2081 the second and subsequent words of multi-word values are ignored.
2083 After the input line is aliased and parsed, and before each command is
2084 executed, variable substitution is performed keyed by
2088 expansion can be prevented by preceding the
2104 are interpreted later (see
2105 .Sx Command substitution
2108 substitution does not occur there until later,
2112 is passed unchanged if followed by a blank, tab, or
2115 Input/output redirections are recognized before variable expansion, and are
2116 variable expanded separately.
2117 Otherwise, the command name and entire argument
2118 list are expanded together.
2119 It is thus possible for the first (command) word
2120 (to this point) to generate more than one word, the first of which becomes the
2121 command name, and the rest of which become arguments.
2127 modifier the results of variable
2128 substitution may eventually be command and filename substituted.
2132 variable whose value consists of multiple words expands to a (portion of a)
2133 single word, with the words of the variable's value separated by blanks.
2137 modifier is applied to a substitution the variable will expand to
2138 multiple words with each word separated by a blank and quoted to prevent later
2139 command or filename substitution.
2141 The following metasequences are provided for introducing variable values into
2143 Except as noted, it is an error to reference a variable which
2146 .Bl -tag -width XXXXXXXXXX -offset indent -compact
2150 Substitutes the words of the value of variable
2156 from following characters which would
2157 otherwise be part of it.
2158 Shell variables have names consisting of
2159 letters and digits starting with a letter.
2160 The underscore character is
2161 considered a letter.
2164 is not a shell variable, but is set in the
2165 environment, then that value is returned (but some of the other forms
2166 given below are not available in this case).
2167 .It Ar $name[selector]
2168 .It Ar ${name[selector]}
2169 Substitutes only the selected words from the value of
2175 substitution and may consist of
2176 a single number or two numbers separated by a
2178 The first word of a variable's value is numbered
2180 If the first number of a range is omitted it defaults to
2182 If the last member of a range is omitted it defaults to
2189 It is not an error for a range to be empty if the
2190 second argument is omitted or in range.
2192 Substitutes the name of the file from which command input
2194 An error occurs if the name is not known.
2202 which is equivalent to
2208 modifiers described under
2209 .Sx History substitution ,
2212 can be applied to the substitutions above.
2213 More than one may be used.
2215 Braces may be needed to insulate a variable substitution from a literal colon
2217 .Sx History substitution
2218 (q.v.); any modifiers must appear
2221 The following substitutions can not be modified with
2225 .Bl -tag -width XXXXXXXXXX -offset indent -compact
2228 Substitutes the string
2238 if the current input filename is known,
2243 in interactive shells.
2246 Substitutes the number of words in
2254 Substitutes the number of characters in
2260 Substitutes the number of characters in
2268 Substitutes the (decimal) process number of the (parent) shell.
2270 Substitutes the (decimal) process number of the last
2271 background process started by this shell.
2274 Substitutes the command line of the last command executed.
2277 Substitutes a line from the standard input, with no further interpretation
2279 It can be used to read from the keyboard in a shell script.
2282 always quotes $<, as if it were equivalent to
2288 is waiting for a line to be
2289 typed the user may type an interrupt to interrupt the sequence into
2290 which the line is to be substituted, but
2292 does not allow this.
2296 .Va expand-variables
2299 can be used to interactively expand individual variables.
2300 .Ss "Command, filename and directory stack substitution"
2301 The remaining substitutions are applied selectively to the arguments
2302 of builtin commands.
2303 This means that portions of expressions which are not evaluated are
2304 not subjected to these expansions.
2305 For commands which are not internal to the
2306 shell, the command name is substituted separately from the argument list.
2307 This occurs very late, after input-output redirection is performed, andk
2308 in a child of the main shell.
2309 .Ss "Command substitution"
2310 Command substitution is indicated by a command enclosed in
2313 from such a command is broken into separate words at blanks, tabs and newlines,
2314 and null words are discarded.
2315 The output is variable and command substituted
2316 and put in place of the original string.
2318 Command substitutions inside double
2321 retain blanks and tabs; only newlines force new words.
2323 final newline does not force a new word in any case.
2324 It is thus possible for a
2325 command substitution to yield only part of a word, even if the command outputs
2328 By default, the shell since version 6.12 replaces all newline and carriage
2329 return characters in the command by spaces.
2330 If this is switched off by
2333 newlines separate commands as usual.
2334 .Ss "Filename substitution"
2335 If a word contains any of the characters
2344 it is a candidate for filename substitution, also known as
2346 This word is then regarded as a pattern
2347 .Dq ( glob-pattern ) ,
2349 replaced with an alphabetically sorted list of file names which match the
2352 In matching filenames, the character
2354 at the beginning of a filename or
2355 immediately following a
2357 as well as the character
2360 explicitly (unless either
2364 or both are set(+)).
2367 matches any string of characters,
2368 including the null string.
2371 matches any single character.
2374 matches any one of the characters enclosed.
2378 characters separated by
2380 matches any character lexically between the two.
2382 (+) Some glob-patterns can be negated:
2385 matches any single character
2388 characters and/or ranges of characters in the braces.
2390 An entire glob-pattern can also be negated with
2392 .Bd -literal -offset indent
2394 bang crash crunch ouch
2399 Glob-patterns which do not use
2407 (below) are not negated correctly.
2413 Left-to-right order is preserved:
2414 .Sq /usr/source/s1/{oldls,ls}.c
2417 .Sq /usr/source/s1/oldls.c /usr/source/s1/ls.c
2418 The results of matches are
2419 sorted separately at a low level to preserve this order:
2422 .Sq ../memo ../box ../mbox
2425 was not sorted with the results of matching
2427 It is not an error when this construct expands to files which do not exist,
2428 but it is possible to get an error from a command to which the expanded list
2430 This construct may be nested.
2431 As a special case the words
2436 are passed undisturbed.
2440 at the beginning of a filename refers to home directories.
2441 Standing alone, i.e.,
2443 it expands to the invoker's home directory as
2444 reflected in the value of the
2448 name consisting of letters, digits and
2450 characters the shell searches for a
2451 user with that name and substitutes their home directory; thus
2462 is followed by a character other than a letter or
2464 or appears elsewhere
2465 than at the beginning of a word, it is left undisturbed.
2467 .Sq setenv MANPATH /usr/man:/usr/local/man:~/lib/man
2469 therefore, do home directory substitution as one might hope.
2471 It is an error for a glob-pattern containing
2480 not to match any files.
2481 However, only one pattern in a list of
2482 glob-patterns must match a file (so that, e.g.,
2485 only if there were no files in the current directory ending in
2492 shell variable is set a pattern (or list
2493 of patterns) which matches nothing is left unchanged rather than causing
2498 shell variable can be set to allow
2503 a file glob pattern that matches any string of characters including
2505 recursively traversing any existing sub-directories.
2508 will list all the .c files in the current directory tree.
2509 If used by itself, it will match zero or more sub-directories
2511 .Sq ls /usr/include/**/time.h
2512 will list any file named
2514 in the /usr/include directory tree;
2515 .Sq ls /usr/include/**time.h
2517 any file in the /usr/include directory tree ending in
2520 .Sq ls /usr/include/**time**.h
2521 will match any .h file with
2524 in a subdirectory name or in the filename itself).
2525 To prevent problems with recursion, the
2527 glob-pattern will not
2528 descend into a symbolic link containing a directory.
2536 shell variable can be set to prevent filename substitution,
2539 editor command, normally bound to
2542 used to interactively expand individual filename substitutions.
2543 .Ss "Directory stack substitution (+)"
2544 The directory stack is a list of directories, numbered from zero, used by the
2549 builtin commands (q.v.).
2551 can print, store in a file, restore and clear the directory stack
2552 at any time, and the
2556 shell variables can be set to
2557 store the directory stack automatically on logout and restore it on login.
2560 shell variable can be examined to see the directory stack and
2561 set to put arbitrary directories into the directory stack.
2565 followed by one or more digits expands to an entry in
2566 the directory stack.
2569 expands to the last directory in
2572 .Bd -literal -offset indent
2589 shell variables and the
2591 editor command apply to directory stack as well as filename substitutions.
2592 .Ss "Other substitutions (+)"
2593 There are several more transformations involving filenames, not strictly
2594 related to the above but mentioned here for completeness.
2596 filename may be expanded to a full path when the
2598 variable (q.v.) is set to
2600 Quoting prevents this expansion, and
2603 editor command does it on demand.
2605 .Va normalize-command
2606 editor command expands commands in PATH into
2607 full paths on demand.
2614 as the old working directory
2615 (equivalent to the shell variable
2617 This is not a substitution at all, but an abbreviation recognized by only
2619 Nonetheless, it too can be prevented by quoting.
2621 The next three sections describe how the shell executes commands and
2622 deals with their input and output.
2623 .Ss "Simple commands, pipelines and sequences"
2624 A simple command is a sequence of words, the first of which specifies the
2625 command to be executed.
2626 A series of simple commands joined by
2630 The output of each command in a pipeline is connected to the
2633 Simple commands and pipelines may be joined into sequences with
2636 be executed sequentially.
2637 Commands and pipelines can also be joined into
2642 indicating, as in the C language, that the second
2643 is to be executed only if the first fails or succeeds respectively.
2645 A simple command, pipeline or sequence may be placed in parentheses,
2647 to form a simple command, which may in turn be a component of a pipeline or
2649 A command, pipeline or sequence can be executed
2650 without waiting for it to terminate by following it with an
2652 .Ss "Builtin and non-builtin command execution"
2653 Builtin commands are executed within the shell.
2654 If any component of a
2655 pipeline except the last is a builtin command, the pipeline is executed
2658 Parenthesized commands are always executed in a subshell.
2659 .Bd -literal -offset indent
2665 directory, leaving you where you were
2666 (printing this after the home directory), while
2667 .Bd -literal -offset indent
2674 Parenthesized commands are most often
2677 from affecting the current shell.
2679 When a command to be executed is found not to be a builtin command the shell
2680 attempts to execute the command via
2682 Each word in the variable
2684 names a directory in which the shell will look for the
2686 If the shell is not given a
2689 hashes the names in these directories into an internal table so that it will
2692 in only a directory where there is a possibility that the
2693 command resides there.
2694 This greatly speeds command location when a large
2695 number of directories are present in the search path. This hashing mechanism is
2698 .Bl -enum -width indent
2700 If hashing is turned explicitly off via
2703 If the shell was given a
2706 For each directory component of
2708 which does not begin with a
2711 If the command contains a
2715 In the above four cases the shell concatenates each component of the path
2716 vector with the given command name to form a path name of a file which it
2717 then attempts to execute it. If execution is successful, the search stops.
2719 If the file has execute permissions but is not an executable to the system
2720 (i.e., it is neither an executable binary nor a script that specifies its
2721 interpreter), then it is assumed to be a file containing shell commands and
2722 a new shell is spawned to read it.
2725 special alias may be set
2726 to specify an interpreter other than the shell itself.
2728 On systems which do not understand the
2730 script interpreter convention
2731 the shell may be compiled to emulate it; see the
2735 If so, the shell checks the first line of the file to
2736 see if it is of the form
2737 .Sq #!interpreter arg ...
2744 file to it on standard input.
2746 The standard input and standard output of a command may be redirected with the
2749 .Bl -tag -width XXXXXXXXX -offset indent -compact
2753 (which is first variable, command and filename
2754 expanded) as the standard input.
2756 Read the shell input up to a line which is identical to
2759 is not subjected to variable, filename or command substitution, and each input
2762 before any substitutions are done on this input
2774 command substitution is performed on the intervening lines, allowing
2782 Commands which are substituted have all blanks, tabs,
2783 and newlines preserved, except for the final newline which is dropped.
2785 resultant text is placed in an anonymous temporary file which is given to the
2786 command as standard input.
2794 is used as standard output.
2795 If the file does not exist
2796 then it is created; if the file exists, it is truncated, its previous contents
2799 If the shell variable
2801 is set, then the file must not exist or be a
2802 character special file (e.g., a terminal or
2804 or an error results.
2805 This helps prevent accidental destruction of files.
2809 can be used to suppress this check.
2815 is allowed on empty files;
2818 is set, an interacive confirmation is presented, rather than an
2823 route the diagnostic output into the specified file as
2824 well as the standard output.
2826 is expanded in the same way as
2828 input filenames are.
2836 , but appends output to the end of
2838 If the shell variable
2840 is set, then it is an error for
2843 to exist, unless one of the
2848 A command receives the environment in which the shell was invoked as modified
2849 by the input-output parameters and the presence of the command in a pipeline.
2850 Thus, unlike some previous shells, commands run from a file of shell commands
2851 have no access to the text of the commands by default; rather they receive the
2852 original standard input of the shell.
2855 mechanism should be used to
2856 present inline data.
2857 This permits shell command scripts to function as
2858 components of pipelines and allows the shell to block read its input.
2860 that the default standard input for a command run detached is
2864 but the original standard input of the shell.
2865 If this is a terminal and if the process attempts to read from the terminal,
2866 then the process will block and the user will be notified (see
2869 Diagnostic output may be directed through a pipe with the standard output.
2875 The shell cannot presently redirect diagnostic output without also redirecting
2876 standard output, but
2877 .Sq \&( command > output-file ) >& error-file
2878 is often an acceptable workaround.
2885 to send output to the terminal.
2887 Having described how the shell accepts, parses and executes
2888 command lines, we now turn to a variety of its useful features.
2890 The shell contains a number of commands which can be used to regulate the
2891 flow of control in command files (shell scripts) and (in limited but
2892 useful ways) from terminal input.
2893 These commands all operate by forcing the
2894 shell to reread or skip in its input and, due to the implementation,
2895 restrict the placement of some of the commands.
2902 statements, as well as the
2906 statement, require that the major
2907 keywords appear in a single simple command on an input line as shown below.
2909 If the shell's input is not seekable, the shell buffers up input whenever
2910 a loop is being read and performs seeks in this internal buffer to
2911 accomplish the rereading implied by the loop.
2912 (To the extent that this allows, backward
2914 s will succeed on non-seekable inputs.)
2922 use expressions with a common syntax.
2923 The expressions can include any
2924 of the operators described in the next three sections.
2927 builtin command (q.v.) has its own separate syntax.
2928 .Ss "Logical, arithmetical and comparison operators"
2929 These operators are similar to those of C and have the same precedence.
2932 .Bl -tag -width XXXXXX -offset indent -compact
2933 .It || && | & == != =~ !~ <= >=
2934 .It < > << >> + \- * / % ! ~ ( )
2937 Here the precedence increases to the right,
2958 groups, at the same level.
2966 their arguments as strings; all others operate on numbers.
2975 except that the right hand side is a
2977 .Sx Filename substitution )
2978 against which the left hand operand is matched.
2979 This reduces the need for use of the
2981 builtin command in shell scripts when all that is really needed is
2985 missing arguments are considered
2987 The results of all expressions are
2988 strings, which represent decimal numbers.
2989 It is important to note that
2990 no two components of an expression can appear in the same word; except
2991 when adjacent to components of expressions which are syntactically
2992 significant to the parser
3000 surrounded by spaces.
3001 .Ss "Command exit status"
3002 Commands can be executed in expressions and their exit status
3003 returned by enclosing them in braces
3005 Remember that the braces should
3006 be separated from the words of the command by spaces.
3008 succeed, returning true, i.e.,
3010 if the command exits with status 0,
3011 otherwise they fail, returning false, i.e.,
3013 If more detailed status
3014 information is required then the command should be executed outside of an
3017 shell variable examined.
3018 .Ss "File inquiry operators"
3019 Some of these operators perform true/false tests on files and related
3021 They are of the form
3027 .Bl -tag -width XXX -offset indent -compact
3035 Executable in the path or shell builtin, e.g.,
3058 Block special file (+)
3060 Character special file (+)
3062 Named pipe (fifo) (+) *
3064 Socket special file (+) *
3066 Set-user-ID bit is set (+)
3068 Set-group-ID bit is set (+)
3070 Sticky bit is set (+)
3072 (which must be a digit) is an open file descriptor
3073 for a terminal device (+)
3075 Has been migrated (Convex only) (+)
3077 Applies subsequent operators in a multiple-operator test to a symbolic link
3078 rather than to the file to which the link points (+) *
3082 is command and filename expanded and then tested to
3083 see if it has the specified relationship to the real user.
3086 does not exist or is inaccessible or, for the operators indicated by
3088 if the specified file type does not exist on the current system,
3089 then all inquiries return false, i.e.,
3092 These operators may be combined for conciseness:
3097 .Sq \&-x file && \&-y file .
3103 for plain executable files, but not for directories.
3106 may be used in a multiple-operator test to apply subsequent operators
3107 to a symbolic link rather than to the file to which the link points.
3110 is true for links owned by the invoking user.
3115 are always true for links and false for
3118 has a different meaning when it is the last operator
3119 in a multiple-operator test; see below.
3121 It is possible but not useful, and sometimes misleading, to combine operators
3124 to be a file with operators which do not
3131 with a non-file operator
3132 can lead to particularly strange results.
3134 Other operators return other information, i.e., not just
3139 They have the same format as before;
3143 .Bl -tag -width XXX -offset indent -compact
3145 Last file access time, as the number of seconds since the epoch
3149 , but in timestamp format, e.g.,
3150 .Sq Fri May 14 16:36:10 1993
3152 Last file modification time
3156 , but in timestamp format
3158 Last inode modification time
3162 , but in timestamp format
3170 ile identifier, in the form
3174 The name of the file pointed to by a symbolic link
3176 Number of (hard) links
3178 Permissions, in octal, without leading zero
3195 is writable by group and other,
3209 Username, or the numeric userid if the username is unknown
3213 Groupname, or the numeric groupid if the groupname is unknown
3218 Only one of these operators may appear in a multiple-operator test, and it
3222 has a different meaning at the end of and
3223 elsewhere in a multiple-operator test.
3226 is a valid return value
3227 for many of these operators, they do not return
3229 when they fail: most
3237 If the shell is compiled with POSIX defined (see the
3240 variable), the result of a file inquiry is based on the permission bits of
3241 the file and not on the result of the
3244 For example, if one tests a file with
3245 .Fl w\fR whose permissions would
3246 ordinarily allow writing but which is on a file system mounted read-only,
3247 the test will succeed in a POSIX shell but fail in a non-POSIX shell.
3249 File inquiry operators can also be evaluated with the
3254 The shell associates a
3258 current jobs, printed by the
3260 command, and assigns them small integer
3262 When a job is started asynchronously with
3264 , the shell prints a
3265 line which looks like
3269 indicating that the job which was started asynchronously was job number 1 and
3270 had one (top-level) process, whose process id was 1234.
3272 If you are running a job and wish to do something else you may hit the suspend
3275 which sends a STOP signal to the current job.
3276 The shell will then normally
3277 indicate that the job has been
3279 and print another prompt.
3282 shell variable is set, all jobs will be listed
3285 builtin command; if it is set to
3288 be in long format, like
3290 You can then manipulate the state of the suspended job.
3291 You can put it in the
3295 command or run some other commands and
3296 eventually bring the job back into the
3305 takes effect immediately and is like an interrupt
3306 in that pending output and unread input are discarded when it is typed.
3309 builtin command causes the shell to wait for all background
3314 key sends a delayed suspend signal, which does not generate a STOP
3315 signal until a program attempts to
3317 (2) it, to the current job.
3318 This can usefully be typed ahead when you have prepared some commands for a
3319 job which you wish to stop after it has read them.
3322 key performs this function in
3327 `^Y' is an editing command.
3330 A job being run in the background stops if it tries to read from the
3332 Background jobs are normally allowed to produce output, but this can
3333 be disabled by giving the command
3335 If you set this tty option,
3336 then background jobs will stop when they try to produce output like they do
3337 when they try to read input.
3339 There are several ways to refer to jobs in the shell.
3342 introduces a job name.
3343 If you wish to refer to job number 1, you can name it
3346 Just naming a job brings it to the foreground; thus
3351 , bringing job 1 back into the foreground.
3354 resumes job 1 in the background, just like
3356 A job can also be named
3357 by an unambiguous prefix of the string typed in to start it:
3360 normally restart a suspended
3362 (1) job, if there were only one suspended
3363 job whose name began with the string
3365 It is also possible to say
3368 ' to specify a job whose text contains
3371 is only one such job.
3373 The shell maintains a notion of the current and previous jobs.
3375 pertaining to jobs, the current job is marked with a
3377 and the previous job
3384 , and (by analogy with the syntax of
3389 all refer to the current job, and
3392 to the previous job.
3394 The job control mechanism requires that the
3400 It is an artifact from a
3402 implementation of the tty
3403 driver which allows generation of interrupt characters from the keyboard to
3410 details on setting options in the new tty driver.
3411 .Ss "Status reporting"
3412 The shell learns immediately whenever a process changes state.
3414 informs you whenever a job becomes blocked so that no further progress is
3415 possible, but only right before it prints a prompt.
3416 This is done so that it
3417 does not otherwise disturb your work.
3418 If, however, you set the shell variable
3420 , the shell will notify you immediately of changes of status in
3422 There is also a shell command
3425 single process so that its status changes will be immediately reported.
3429 marks the current process; simply say
3432 starting a background job to mark it.
3434 When you try to leave the shell while jobs are stopped, you will be
3436 .Sq There are suspended jobs.
3441 If you do this or immediately try to exit again, the shell
3442 will not warn you a second time, and the suspended jobs will be terminated.
3443 .Ss "Automatic, periodic and timed events (+)"
3444 There are various ways to run commands and take other actions automatically
3445 at various times in the
3448 They are summarized here,
3449 and described in detail under the appropriate
3450 .Va Builtin commands
3452 .Va Special shell variables
3458 builtin command puts commands in a scheduled-event list,
3459 to be executed by the shell at a given time.
3475 can be set, respectively, to execute commands when the shell wants
3476 to ring the bell, when the working directory changes, every
3478 minutes, before each prompt, before each command gets executed, after each
3479 command gets executed, and when a job is started or is brought into the
3484 shell variable can be set to log out or lock the shell
3485 after a given number of minutes of inactivity.
3489 shell variable can be set to check for new mail periodically.
3493 shell variable can be set to print the exit status
3494 of commands which exit with a status other than zero.
3498 shell variable can be set to ask the user, when
3501 typed, if that is really what was meant.
3505 shell variable can be set to execute the
3508 command after the completion of any process that takes more than a given
3509 number of CPU seconds.
3515 shell variables can be set to report when
3516 selected users log in or out, and the
3518 builtin command reports
3519 on those users at any time.
3520 .Ss "Native Language System support (+)"
3521 The shell is eight bit clean
3522 (if so compiled; see the
3525 and thus supports character sets needing this capability.
3526 NLS support differs depending on whether or not
3527 the shell was compiled to use the system's NLS (again, see
3530 In either case, 7-bit ASCII is the default character code
3531 (e.g., the classification of which characters are printable) and sorting,
3536 environment variables
3537 causes a check for possible changes in these respects.
3539 When using the system's NLS, the
3541 (3) function is called
3542 to determine appropriate character code/classification and sorting
3543 (e.g., a 'en_CA.UTF-8' would yield "UTF-8" as a character code).
3544 This function typically examines the
3548 environment variables; refer to the system documentation for further details.
3549 When not using the system's NLS, the shell simulates it by assuming that the
3550 ISO 8859-1 character set is used
3551 whenever either of the
3555 variables are set, regardless of
3557 Sorting is not affected for the simulated NLS.
3559 In addition, with both real and simulated NLS, all printable
3560 characters in the range \e200\-\e377, i.e., those that have
3563 bindings, are automatically rebound to
3564 .Va self-insert-command
3565 The corresponding binding for the escape-
3567 sequence, if any, is
3569 These characters are not rebound if the
3571 environment variable
3573 This may be useful for the simulated NLS or a primitive real NLS
3574 which assumes full ISO 8859-1.
3578 range \e240\-\e377 are effectively undone.
3579 Explicitly rebinding the relevant keys with
3581 is of course still possible.
3583 Unknown characters (i.e., those that are neither printable nor control
3584 characters) are printed in the format \ennn.
3585 If the tty is not in 8 bit mode, other 8 bit characters are printed by
3586 converting them to ASCII and using standout mode.
3588 never changes the 7/8 bit mode of the tty and tracks user-initiated
3589 changes of 7/8 bit mode.
3590 NLS users (or, for that matter, those who want to
3591 use a meta key) may need to explicitly set
3592 the tty in 8 bit mode through the appropriate
3595 command in, e.g., the
3598 .Ss "OS variant support (+)"
3599 A number of new builtin commands are provided to support features in
3600 particular operating systems.
3601 All are described in detail in the
3602 .Va Builtin commands
3605 On systems that support TCF (aix-ibm370, aix-ps2),
3609 get and set the system execution path,
3613 get and set the experimental version prefix
3616 migrates processes between sites.
3620 prints the site on which each job is executing.
3624 executes commands of the underlying BS2000/OSD
3629 adds shared libraries to the current environment,
3631 changes the rootnode and
3633 changes the systype.
3637 is equivalent to Mach's
3641 Under Masscomp/RTU and Harris CX/UX,
3649 runs a command under the specified
3654 prints or sets the universe.
3662 environment variables
3663 indicate respectively the vendor, operating system and machine type
3664 (microprocessor class or machine model) of the
3665 system on which the shell thinks it is running.
3666 These are particularly useful when sharing one's home directory between several
3667 types of machines; one can, for example,
3669 set path = (~/bin.$MACHTYPE /usr/ucb /bin /usr/bin .)
3673 and put executables compiled for each machine in the
3674 appropriate directory.
3679 variable indicates what options were chosen when the shell was compiled.
3687 shell variables and the system-dependent locations of
3688 the shell's input files (see
3691 .Ss "Signal handling"
3692 Login shells ignore interrupts when reading the file
3694 The shell ignores quit signals unless started with
3696 Login shells catch the terminate signal, but non-login shells inherit the
3697 terminate behavior from their parents.
3698 Other signals have the values which the shell inherited from its parent.
3700 In shell scripts, the shell's handling of interrupt and terminate signals
3701 can be controlled with
3703 , and its handling of hangups can be
3709 The shell exits on a hangup (see also the
3713 default, the shell's children do too, but the shell does not send them a
3714 hangup when it exits.
3716 arranges for the shell to send a hangup to
3717 a child when it exits, and
3719 sets a child to ignore hangups.
3720 .Ss "Terminal management (+)"
3721 The shell uses three different sets of terminal (
3724 `edit', used when editing,
3726 , used when quoting literal characters,
3729 , used when executing commands.
3730 The shell holds some settings in each mode constant, so commands which leave
3731 the tty in a confused state do not interfere with the shell.
3732 The shell also matches changes in the speed and padding of the tty.
3733 The list of tty modes that are kept constant
3734 can be examined and modified with the
3737 Note that although the editor uses CBREAK mode (or its equivalent),
3738 it takes typed-ahead characters anyway.
3746 commands can be used to
3747 manipulate and debug terminal capabilities from the command line.
3749 On systems that support SIGWINCH or SIGWINDOW, the shell
3750 adapts to window resizing automatically and adjusts the environment
3759 contains li# and co# fields, the shell adjusts
3760 them to reflect the new window size.
3762 The next sections of this manual describe all of the available
3763 .Va Builtin commands
3767 .Va Special shell variables
3768 .Ss "Builtin commands"
3769 .Bl -tag -width XXXXXXX -offset indent
3779 Does nothing, successfully.
3782 .It Ar @ name = expr
3783 .It Ar @ name[index] = expr
3785 .It Ar @name[index]++|--
3786 The first form prints the values of all shell variables.
3788 The second form assigns the value of
3792 The third form assigns the value of
3807 may contain the operators
3822 then at least that part of
3824 must be placed within
3826 Note that the syntax of
3828 has nothing to do with that described
3832 The fourth and fifth forms increment (
3857 must be separated by spaces.
3858 .It Ar alias[name[wordlist]]
3859 Without arguments, prints all aliases.
3862 , prints the alias for name.
3872 is command and filename substituted.
3882 Shows the amount of dynamic memory acquired, broken down into used and free
3884 With an argument shows the number of free and used blocks in each size
3886 The categories start at size 8 and double at each step.
3888 command's output may vary across system types, because systems other than the VAX
3889 may use a different memory allocator.
3892 Puts the specified jobs (or, without arguments, the current job)
3893 into the background, continuing each if it is stopped.
3895 may be a number, a string,
3907 .It Ar bindkey Oo Fl l Ns | Ns Fl d Ns | Ns Fl e Ns | Ns Fl v Ns | Ns Fl u Oc (+)
3908 .It Ar bindkey Oo Fl a Oc Oo Fl b Oc Oo Fl k Oc Oo Fl r Oc Oo Fl Fl Oc Ar key (+)
3909 .It Ar bindkey Oo Fl a Oc Oo Fl b Oc Oo Fl k Oc Oo Fl c Ns | Ns Fl s Oc Oo Fl Fl Oc Ar key command (+)
3910 .\" .It Ar macro can't take too many words, so I used \fB in the previous tags
3911 Without options, the first form lists all bound keys and the editor command to which each is bound,
3912 the second form lists the editor command to which
3915 the third form binds the editor command
3921 .Bl -tag -width XXX -compact
3923 Lists all editor commands and a short description of each.
3925 Binds all keys to the standard bindings for the default editor,
3934 (1)\-style bindings.
3940 (1)\-style bindings.
3944 Lists or changes key-bindings in the alternative key map.
3945 This is the key map used in
3951 a control character written ^
3961 a meta character written M-
3966 a function key written F-
3971 or an extended prefix key written X-
3978 is interpreted as a symbolic arrow key name, which may be one of
3996 .Va self-insert-command
4002 is interpreted as a builtin or external command instead of an
4006 is taken as a literal string and treated as terminal input
4013 reinterpreted, and this continues for ten levels of interpretation.
4015 Forces a break from option processing, so the next word is taken as
4017 even if it begins with '\&-'.
4019 (or any invalid option)
4020 Prints a usage message.
4024 may be a single character or a string.
4025 If a command is bound to a string, the first character of the string is bound to
4026 .Va sequence-lead-in
4027 and the entire string is bound to the command.
4029 Control characters in
4031 can be literal (they can be typed by preceding
4032 them with the editor command
4037 written caret-character style, e.g.,
4041 (caret-question mark).
4045 can contain backslashed
4046 escape sequences (in the style of System V
4050 .Bl -tag -width XXXX -compact -offset indent
4068 The ASCII character corresponding to the octal number
4072 `\e' nullifies the special meaning of the following character, if it has
4077 .It bs2cmd Va bs2000-command
4081 to the BS2000 command interpreter for
4082 execution. Only non-interactive commands can be executed, and it is
4083 not possible to execute any command that would overlay the image
4084 of the current process, like /EXECUTE or /CALL-PROCEDURE. (BS2000 only)
4086 Causes execution to resume after the
4093 The remaining commands on the
4094 current line are executed.
4095 Multi-level breaks are thus
4096 possible by writing them all on one line.
4098 Causes a break from a
4100 , resuming after the
4104 Prints the names of all builtin commands.
4110 Available only if the shell was so compiled;
4115 .It case \fIlabel\fB:
4118 statement as discussed below.
4124 .Fl v\fR] [\I--\fR] [
4129 is given, changes the shell's working directory
4136 variable is not set, in which case a
4143 it is interpreted as the previous working directory
4145 .Va Other substitutions
4150 is not a subdirectory of the current directory
4151 (and does not begin with
4157 ), each component of the variable
4159 is checked to see if it has a subdirectory
4164 is a shell variable whose value
4167 or '.', then this is tried to see if it is a directory, and
4169 .Fl p\fR option is implied.
4173 .Fl p\fR, prints the final directory stack, just like
4178 .Fl v\fR flags have the same effect on
4186 .Fl \-\fR forces a break from option processing so the next word
4187 is taken as the directory
4189 even if it begins with '\-'. (+)
4205 [\fIword\fB/\fIpattern\fB/
4216 Without arguments, lists all completions.
4219 , lists completions for
4225 etc., defines completions.
4229 may be a full command name or a glob-pattern
4231 .Va Filename substitution
4236 completion should be used only when
4241 specifies which word relative to the current word
4242 is to be completed, and may be one of the following:
4248 Current-word completion.
4250 is a glob-pattern which must match the beginning of the current word on
4253 is ignored when completing the current word.
4260 when completing the current word.
4263 Next-word completion.
4265 is a glob-pattern which must match the beginning of the previous word on
4271 , but must match the beginning of the word two before the current word.
4274 Position-dependent completion.
4276 is a numeric range, with the same syntax used to index shell
4277 variables, which must include the current word.
4282 , the list of possible completions, may be one of the following:
4288 Bindings (editor commands)
4290 Commands (builtin or external commands)
4292 External commands which begin with the supplied path prefix
4296 Directories which begin with the supplied path prefix
4298 Environment variables
4302 Filenames which begin with the supplied path prefix
4322 files which begin with the supplied path prefix
4339 Words from the variable
4342 Words from the given list
4344 Words from the output of command
4348 is an optional glob-pattern.
4349 If given, words from only
4356 shell variable is ignored.
4357 The last three types of completion may not have a
4363 as an explanatory message when
4366 editor command is used.
4369 is a single character to be appended to a successful
4371 If null, no character is appended.
4372 If omitted (in which
4373 case the fourth delimiter can also be omitted), a slash is appended to
4374 directories and a space to other words.
4377 invoked from \`...\` version has additional environment
4378 variable set, the variable name is \%
4381 contains (as its name indicates) contents of the current (already
4382 typed in) command line. One can examine and use contents of the
4385 \% variable in her custom script to build more
4386 sophisticated completions (see completion for svn(1) included in
4389 Now for some examples.
4390 Some commands take only directories as arguments,
4391 so there's no point completing plain files.
4393 > complete cd 'p/1/d/'
4395 completes only the first word following
4397 (`p/1') with a directory.
4399 -type completion can also be used to narrow down command completion:
4405 > complete \-co* 'p/0/(compress)/'
4411 This completion completes commands (words in position 0,
4424 indicates that this completion is to be used with only
4427 > complete find 'n/\-user/u/'
4435 immediately following
4437 is completed from the list of users.
4439 > complete cc 'c/\-I/d/'
4449 is completed as a directory.
4450 `\-I' is not taken as part of the
4451 directory because we used lowercase
4456 s are useful with different commands.
4458 > complete alias 'p/1/a/'
4460 > complete man 'p/*/c/'
4462 > complete set 'p/1/s/'
4464 > complete true 'p/1/x:Truth has no options./'
4466 These complete words following
4473 with shell variables.
4474 `true' doesn't have any options, so
4476 does nothing when completion
4477 is attempted and prints
4478 .Sq Truth has no options.
4479 when completion choices are listed.
4483 example, and several other examples below, could
4484 just as well have used 'c/*' or 'n/*' as 'p/*'.
4486 Words can be completed from a variable evaluated at completion time,
4488 > complete ftp 'p/1/$hostnames/'
4490 > set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu)
4494 rtfm.mit.edu tesla.ee.cornell.edu
4498 > set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net)
4502 rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net
4504 or from a command run at completion time:
4506 > complete kill 'p/*/\`ps | awk \e{print\e \e$1\e}\`/'
4510 23113 23377 23380 23406 23429 23529 23530 PID
4514 command does not itself quote its arguments,
4515 so the braces, space and
4519 must be quoted explicitly.
4521 One command can have multiple completions:
4523 > complete dbx 'p/2/(core)/' 'p/*/c/'
4525 completes the second argument to
4530 arguments with commands.
4531 Note that the positional completion is specified
4532 before the next-word completion.
4533 Because completions are evaluated from left to right, if
4534 the next-word completion were specified first it would always match
4535 and the positional completion would never be executed.
4537 common mistake when defining a completion.
4541 pattern is useful when a command takes files with only
4542 particular forms as arguments.
4545 > complete cc 'p/*/f:*.[cao]/'
4549 arguments to files ending in only
4556 can also exclude files, using negation of a glob-pattern as
4558 .Va Filename substitution
4561 > complete rm 'p/*/f:^*.{c,h,cc,C,tex,1,man,l,y}/'
4563 to exclude precious source code from
4567 could still type excluded names manually or override the completion
4569 .Va complete-word-raw
4571 .Va list-choices-raw
4572 editor commands (q.v.).
4592 respectively, but they use the
4594 argument in a different way: to
4595 restrict completion to files beginning with a particular path prefix.
4597 example, the Elm mail program uses
4599 as an abbreviation for one's mail
4603 > complete elm c@=@F:$HOME/Mail/@
4613 to avoid confusion with the
4615 argument, and we used
4618 because home directory substitution works at only the
4619 beginning of a word.
4622 is used to add a nonstandard suffix
4625 for directories) to completed words.
4627 > complete finger 'c/*@/$hostnames/' 'p/1/u/@'
4629 completes arguments to
4631 from the list of users, appends an
4634 and then completes after the
4640 again the order in which the completions are specified.
4642 Finally, here's a complex example for inspiration:
4646 \&'n/\-name/f/' 'n/\-newer/f/' 'n/\-{,n}cpio/f/' \e
4648 \&\'n/\-exec/c/' 'n/\-ok/c/' 'n/\-user/u/' \e
4650 \&'n/\-group/g/' 'n/\-fstype/(nfs 4.2)/' \e
4652 \&'n/\-type/(b c d f l p s)/' \e
4654 \'c/\-/(name newer cpio ncpio exec ok user \e
4656 group fstype type atime ctime depth inum \e
4658 ls mtime nogroup nouser perm print prune \e
4664 This completes words following
4672 (note the pattern which matches both) to files,
4677 to commands, words following
4681 to users and groups respectively
4688 It also completes the switches themselves from the given list
4692 and completes anything not otherwise completed to a directory.
4695 Remember that programmed completions are ignored if the word being completed
4696 is a tilde substitution (beginning with
4698 ) or a variable (beginning with
4707 Continues execution of the nearest enclosing
4711 The rest of the commands on the current line are executed.
4714 Labels the default case in a
4717 It should come after all
4733 The first form prints the directory stack.
4734 The top of the stack is at the
4735 left and the first directory in the stack is the current directory.
4741 in the output is expanded explicitly
4744 or the pathname of the home directory for user \fIname\fP.
4747 .Fl n\fR, entries are wrapped before they reach the edge of the screen.
4750 .Fl v\fR, entries are printed one per line, preceded by their stack positions.
4755 .Fl v\fR takes precedence.
4756 .Fl p\fR is accepted but does nothing.
4761 .Fl S\fR, the second form saves the directory stack to
4769 .Fl L\fR, the shell sources
4771 , which is presumably
4772 a directory stack file saved by the
4773 .Fl S\fR option or the
4786 Note that login shells do the equivalent of
4796 is normally sourced before
4805 The last form clears the directory stack.
4814 to the shell's standard
4815 output, separated by spaces and terminated with a newline.
4818 shell variable may be set to emulate (or not) the flags and escape
4819 sequences of the BSD and/or System V versions of
4829 Exercises the terminal capabilities (see
4833 For example, 'echotc home' sends the cursor to the home position,
4834 \&'echotc cm 3 10' sends it to column 3 and row 10, and
4835 \&'echotc ts 0; echo "This is a test."; echotc fs' prints "This is a test."
4841 is 'baud', 'cols', 'lines', 'meta' or 'tabs', prints the
4842 value of that capability ("yes" or "no" indicating that the terminal does
4843 or does not have that capability).
4844 One might use this to make the output
4845 from a shell script less verbose on slow terminals, or limit command
4846 output to the number of lines on the screen:
4848 > set history=\`echotc lines\`
4852 Termcap strings may contain wildcards which will not echo correctly.
4853 One should use double quotes when setting a shell variable to a terminal
4854 capability string, as in the following example that places the date in
4857 > set tosl="\`echotc ts 0\`"
4859 > set frsl="\`echotc fs\`"
4861 > echo \-n "$tosl";date; echo \-n "$frsl"
4864 .Fl s\fR, nonexistent capabilities return the empty string rather
4865 than causing an error.
4867 .Fl v\fR, messages are verbose.
4878 See the description of the
4892 Treats the arguments as input to the
4893 shell and executes the resulting command(s) in the context
4894 of the current shell.
4895 This is usually used to execute commands
4896 generated as the result of command or variable substitution,
4897 because parsing occurs before these substitutions.
4900 (1) for a sample use of
4905 Executes the specified command in place of the current shell.
4910 The shell exits either with the value of the specified
4912 (an expression, as described under
4922 Brings the specified jobs (or, without arguments, the current job)
4923 into the foreground, continuing each if it is stopped.
4925 may be a number, a string,
4945 (which is a file inquiry operator as described under
4946 .Va File inquiry operators
4949 and returns the results as a
4950 space-separated list.
4952 .B foreach \fIname \fB(\fIwordlist\fB)
4958 Successively sets the variable
4962 and executes the sequence of commands between this command
4969 must appear alone on separate lines.) The builtin command
4971 may be used to continue the loop prematurely and
4974 to terminate it prematurely.
4975 When this command is read from the terminal, the loop is read once
4980 ) before any statements in
4981 the loop are executed.
4982 If you make a mistake typing in a
4983 loop at the terminal you can rub it out.
4987 Prints the system execution path.
4991 Prints the experimental version prefix.
4999 parameter is not recognized and words are
5000 delimited by null characters in the output.
5002 programs which wish to use the shell to filename expand a list of words.
5006 is filename and command-substituted to
5007 yield a string of the form
5009 The shell rewinds its
5010 input as much as possible, searches for a line of the
5013 , possibly preceded by blanks or tabs, and
5014 continues execution after that line.
5017 Prints a statistics line indicating how effective the
5018 internal hash table has been at locating commands (and avoiding
5023 is attempted for each component of the
5025 where the hash function indicates a possible hit, and
5026 in each component which does not begin with a
5031 (2), prints only the number and size of
5046 .B history \-c \fR(+)
5047 The first form prints the history event list.
5052 most recent events are printed or saved.
5054 .Fl h\fR, the history list is printed without leading numbers.
5057 is specified, timestamps are printed also in comment form.
5058 (This can be used to
5059 produce files suitable for loading with 'history \-L' or 'source \-h'.)
5061 .Fl r\fR, the order of printing is most recent
5062 first rather than oldest first.
5067 .Fl S\fR, the second form saves the history list to
5069 If the first word of the
5071 shell variable is set to a
5072 number, at most that many lines are saved.
5073 If the second word of
5077 , the history list is merged with the
5078 existing history file instead of replacing it (if there is one) and
5079 sorted by time stamp.
5080 (+) Merging is intended for an environment like
5082 with several shells in simultaneous use.
5083 If the second word of
5087 and the third word is set to
5089 , the history file update
5090 will be serialized with other shell sessions that would possibly like
5091 to merge history at exactly the same time.
5094 .Fl L\fR, the shell appends
5096 , which is presumably a
5097 history list saved by the
5098 .Fl S\fR option or the
5101 to the history list.
5103 .Fl L\fR, but the contents of
5106 into the history list and sorted by timestamp.
5116 `history \-L' is exactly like 'source \-h' except that it does not require a
5119 Note that login shells do the equivalent of
5129 is normally sourced before
5140 is set, the first and second forms print and save the literal
5141 (unexpanded) form of the history list.
5143 The last form clears the history list.
5153 such that it will exit on a hangup
5154 signal and arranges for the shell to send it a hangup signal when the shell
5156 Note that commands may set their own response to hangups, overriding
5158 Without an argument, causes the non-interactive shell only to
5159 exit on a hangup for the remainder of the script.
5166 .B if (\fIexpr\fB) \fIcommand
5169 (an expression, as described under
5172 evaluates true, then
5175 Variable substitution on
5177 happens early, at the same time it
5178 does for the rest of the
5182 must be a simple command, not an alias, a pipeline, a command list
5183 or a parenthesized command list, but it may have arguments.
5184 Input/output redirection occurs even if
5191 executed; this is a bug.
5193 .B if (\fIexpr\fB) then
5197 .B else if (\fIexpr2\fB) then
5209 is true then the commands to the
5212 are executed; otherwise if
5215 the commands to the second
5221 pairs are possible; only one
5227 part is likewise optional.
5232 must appear at the beginning of input lines;
5235 must appear alone on its input line or after an
5245 to the current environment.
5247 to remove a shared library.
5252 Lists the active jobs.
5254 .Fl l\fR, lists process
5255 IDs in addition to the normal information.
5256 On TCF systems, prints
5257 the site on which each job is executing.
5272 The first and second forms sends the specified
5275 is given, the TERM (terminate) signal) to the specified jobs or processes.
5277 may be a number, a string,
5288 Signals are either given by number or by name (as given in
5289 .Va /usr/include/signal.h
5290 , stripped of the prefix
5297 does not send a signal
5299 If the signal being sent is TERM (terminate)
5300 or HUP (hangup), then the job or process is sent a
5301 CONT (continue) signal as well.
5302 The third form lists the signal names.
5311 Limits the consumption by the current process and each
5312 process it creates to not individually exceed
5320 the current limit is printed; if no
5323 all limitations are given.
5325 .Fl h\fR flag is given, the
5326 hard limits are used instead of the current limits.
5328 hard limits impose a ceiling on the values of the current
5330 Only the super-user may raise the hard limits, but
5331 a user may lower or raise the current limits within the legal range.
5333 Controllable resources currently include (if supported by the OS):
5334 .Bl -tag -width pseudoterminals -compact -offset indent
5336 the maximum number of cpu-seconds to be used by each process
5338 the largest single file which can be created
5340 the maximum growth of the data+stack region via sbrk(2) beyond
5341 the end of the program text
5343 the maximum size of the automatically-extended stack region
5345 the size of the largest core dump that will be created
5347 the maximum amount of physical memory a process
5348 may have allocated to it at a given time
5350 the maximum amount of virtual memory a process
5351 may have allocated to it at a given time (address space)
5353 the maximum amount of virtual memory a process
5354 may have allocated to it at a given time
5356 the maximum amount of memory a process
5363 the maximum number of open files for this process
5364 .It Va pseudoterminals
5365 the maximum number of pseudo-terminals for this user
5367 the maximum number of kqueues allocated for this process
5369 the maximum number of threads for this process
5371 the maximum size which a process may lock into memory using mlock(2)
5373 the maximum number of simultaneous processes for this user id
5375 the maximum number of simultaneous threads (lightweight processes) for this
5378 the maximum number of threads for this process
5380 the maximum size of socket buffer usage for this user
5382 the maximum amount of swap space reserved or used for this user
5384 the maximum number of locks for this user
5386 the maximum number of POSIX advisory locks for this user
5388 the maximum number of pending signals for this user
5390 the maximum number of bytes in POSIX mqueues for this user
5392 the maximum nice priority the user is allowed to raise mapped from [19...-20]
5393 to [0...39] for this user
5395 the maximum realtime priority for this user
5397 the timeout for RT tasks in microseconds for this user.
5401 may be given as a (floating point or
5402 integer) number followed by a scale factor.
5406 the default scale is
5410 (1024 bytes); a scale factor of
5421 the default scaling is
5427 for hours, or a time of the
5430 giving minutes and seconds may be used.
5436 then the limitation on the specified
5438 is removed (this is equivalent to the
5444 names and scale factors, unambiguous
5445 prefixes of the names suffice.
5451 shell variable and reports on each user indicated
5454 who is logged in, regardless of when they last logged in.
5459 Terminates a login shell, replacing it with an instance of
5461 . This is one way to log off, included for
5466 Terminates a login shell.
5467 Especially useful if
5479 It identifies each type of
5480 special file in the listing with a special character:
5481 .Bl -tag -width x -offset indent -compact
5491 Named pipe (systems with named pipes only)
5493 Socket (systems with sockets only)
5495 Symbolic link (systems with symbolic links only)
5497 Hidden directory (AIX only) or context dependent (HP/UX only)
5499 Network special (HP/UX only)
5504 shell variable is set, symbolic links are identified
5505 in more detail (on only systems that have them, of course):
5510 Symbolic link to a non-directory
5513 Symbolic link to a directory
5516 Symbolic link to nowhere
5520 also slows down \fIls\-F\fR and causes partitions holding
5521 files pointed to by symbolic links to be mounted.
5525 shell variable is set to
5532 combination thereof (e.g.,
5534 ), they are used as flags to \fIls\-F\fR,
5547 is not the default, \fIls\-F\fR acts like
5554 , in which case it acts like
5556 \fIls\-F\fR passes its arguments to
5558 (1) if it is given any switches,
5561 generally does the right thing.
5563 The \fBls\-F\fR builtin can list files using different colors depending on the
5564 filetype or extension.
5567 shell variable and the
5569 environment variable.
5585 The first form migrates the process or job to the site specified or the
5586 default site determined by the system path.
5587 The second form is equivalent to
5592 current process to the specified site.
5594 itself can cause unexpected behavior, because the shell
5595 does not like to lose its tty.
5608 Available only if the shell was so compiled;
5618 Sets the scheduling priority for the shell to
5633 The super-user may specify negative
5635 .Sq nice \-number ...
5637 executed in a sub-shell, and the restrictions placed on
5649 such that it will ignore hangup signals.
5650 Note that commands may set their own response to hangups, overriding
5652 Without an argument, causes the non-interactive shell only to
5653 ignore hangups for the remainder of the script.
5663 Causes the shell to notify the user asynchronously when the status of any
5664 of the specified jobs (or, without %
5666 , the current job) changes,
5667 instead of waiting until the next prompt as is usual.
5669 may be a number, a string,
5688 Controls the action of the shell on interrupts.
5690 restores the default action of the shell on interrupts,
5691 which is to terminate shell scripts or to return to the
5692 terminal command input level.
5695 , causes all interrupts to be ignored.
5698 , causes the shell to execute a
5701 when an interrupt is received or a child process terminates because it was
5705 is ignored if the shell is running detached and in system
5708 ), where interrupts are disabled anyway.
5717 Without arguments, pops the directory stack and returns to the new top directory.
5723 'th entry in the stack.
5725 Finally, all forms of
5727 print the final directory stack,
5732 shell variable can be set to
5733 prevent this and the
5734 .Fl p\fR flag can be given to override
5739 .Fl v\fR flags have the same effect on
5748 Prints the names and values of all environment variables or,
5751 , the value of the environment variable
5763 Without arguments, exchanges the top two elements of the directory stack.
5768 without arguments does
5776 , pushes the current working directory onto the directory
5777 stack and changes to
5783 it is interpreted as the previous working directory
5785 .Va Filename substitution
5792 removes any instances of
5794 from the stack before pushing it onto the stack.
5802 directory stack around to be the top element and changes to it.
5811 directory, pushes it onto the top of the stack and changes to it.
5814 Finally, all forms of
5816 print the final directory stack,
5821 shell variable can be set to
5822 prevent this and the
5823 .Fl p\fR flag can be given to override
5828 .Fl v\fR flags have the same effect on
5835 Causes the internal hash table of the contents of the
5838 variable to be recomputed.
5842 shell variable is not set and new
5843 commands are added to directories in
5845 while you are logged
5849 , a new command will be found
5850 automatically, except in the special case where another command of
5851 the same name which is located in a different directory already
5852 exists in the hash table.
5853 Also flushes the cache of home directories
5854 built by tilde expansion.
5856 .B repeat \fIcount command
5860 which is subject to the same restrictions as the
5864 statement above, is executed
5867 I/O redirections occur exactly once, even if
5874 Changes the rootnode to //
5896 The first form prints the scheduled-event list.
5899 shell variable may be set to define the format in which
5900 the scheduled-event list is printed.
5901 The second form adds
5903 to the scheduled-event list.
5908 > sched 11:00 echo It\e's eleven o\e'clock.
5910 causes the shell to echo
5911 .Sq It's eleven o'clock .
5913 The time may be in 12-hour AM/PM format
5916 > sched 5pm set prompt='[%h] It\e's after 5; go home: >'
5918 or may be relative to the current time:
5920 > sched +2:15 /usr/lib/uucp/uucico \-r1 \-sother
5922 A relative time specification may not use AM/PM format.
5923 The third form removes item
5925 from the event list:
5926 .Bd -literal -offset indent
5928 1 Wed Apr 4 15:42 /usr/lib/uucp/uucico \-r1 \-sother
5929 2 Wed Apr 4 17:00 set prompt=[%h] It's after 5; go home: >
5932 1 Wed Apr 4 15:42 /usr/lib/uucp/uucico \-r1 \-sother
5935 A command in the scheduled-event list is executed just before the first
5936 prompt is printed after the time when the command is scheduled.
5937 It is possible to miss the exact time when the command is to be run, but
5938 an overdue command will execute at the next prompt.
5939 A command which comes due while the shell
5940 is waiting for user input is executed immediately.
5941 However, normal operation of an already-running command will not
5942 be interrupted so that a scheduled-event list element may be run.
5944 This mechanism is similar to, but not the same as, the
5947 command on some Unix systems.
5948 Its major disadvantage is that it may not run a command at exactly the
5950 Its major advantage is that because
5953 the shell, it has access to shell variables and other structures.
5954 This provides a mechanism for changing one's working environment
5955 based on the time of day.
5970 .B set [\-r] [\-f|\-l]
5994 The first form of the command prints the value of all shell variables.
5995 Variables which contain more than a single word print as a
5996 parenthesized word list.
5997 The second form sets
6004 The fourth form sets
6006 to the list of words in
6008 In all cases the value is command and filename expanded.
6010 .Fl r\fR is specified, the value is set read-only.
6013 .Fl l\fR are specified, set only unique words keeping their order.
6014 .Fl f\fR prefers the first occurrence of a word, and
6016 The fifth form sets the
6023 this component must already exist.
6024 The sixth form lists only the names of all shell variables that are read-only.
6025 The seventh form makes
6027 read-only, whether or not it has a value.
6028 The eighth form is the same as the third form, but
6031 read-only at the same time.
6034 These arguments can be repeated to set and/or make read-only multiple variables
6035 in a single set command.
6036 Note, however, that variable expansion
6037 happens for all arguments before any setting occurs.
6045 or separated from both by
6046 whitespace, but cannot be adjacent to only one or the other.
6056 Without arguments, prints the names and values of all environment variables.
6059 , sets the environment variable
6065 , to the null string.
6075 .B setspath\fR LOCAL|
6081 Sets the system execution path.
6087 Tells the shell to believe that the terminal capability
6093 No sanity checking is done.
6094 Concept terminal users may have to
6097 wrapping at the rightmost column.
6109 Controls which tty modes (see
6110 .Va Terminal management
6112 the shell does not allow to change.
6124 set of tty modes respectively; without
6131 Without other arguments,
6133 lists the modes in the chosen set
6134 which are fixed on (`+mode') or off (`\-mode').
6135 The available modes, and thus the display, vary from system to system.
6137 .Fl a\fR, lists all tty modes in the chosen set
6138 whether or not they are fixed.
6149 or removes control from
6153 .Sq setty +echok echoe
6156 mode on and allows commands
6159 mode on or off, both when the shell is executing commands.
6164 Set the experimental version prefix to
6175 Without arguments, discards
6177 [1] and shifts the members of
6182 not to be set or to have
6183 less than one word as value.
6196 The shell reads and executes commands from
6198 The commands are not placed on the history list.
6201 are given, they are placed in
6205 commands may be nested;
6206 if they are nested too deeply the shell may run out of file descriptors.
6209 at any level terminates all nested
6213 .Fl h\fR, commands are placed on the history list instead of being
6222 Stops the specified jobs or processes which are executing in the background.
6224 may be a number, a string,
6243 Causes the shell to stop in its tracks, much as if it had
6244 been sent a stop signal with
6246 This is most often used to
6247 stop shells started by
6251 .B switch (\fIstring\fB)
6269 Each case label is successively matched, against the
6272 which is first command and filename expanded.
6273 The file metacharacters
6280 in the case labels, which are variable expanded.
6282 of the labels match before a
6284 label is found, then
6285 the execution begins after the default label.
6287 label and the default label must appear at the beginning of
6291 causes execution to continue
6294 Otherwise control may fall through case
6295 labels and default labels as in C.
6296 If no label matches and
6297 there is no default, execution continues after the
6302 Lists the values of all terminal capabilities (see
6311 (or the current value of
6315 is given) has an entry in the hosts termcap(5) or
6316 terminfo(5) database. Prints the terminal type to stdout and returns 0
6317 if an entry is present otherwise returns 1.
6324 (which must be a simple command, not an alias,
6325 a pipeline, a command list or a parenthesized command list)
6326 and prints a time summary as described under the
6329 If necessary, an extra shell is created to print the time statistic when
6330 the command completes.
6333 , prints a time summary for the current shell and its
6339 Sets the file creation mask to
6341 , which is given in octal.
6342 Common values for the mask are
6343 002, giving all access to the group and read and execute access to others, and
6344 022, giving read and execute access to the group and others.
6347 , prints the current file creation mask.
6352 Removes all aliases whose names match
6354 `unalias *' thus removes all aliases.
6355 It is not an error for nothing to be
6362 Removes all completions whose names match
6364 `uncomplete *' thus removes all completions.
6365 It is not an error for nothing to be
6370 Disables use of the internal hash table to speed location of
6376 Sets the universe to
6384 Removes the limitation on
6393 .Fl h\fR, the corresponding hard limits are removed.
6394 Only the super-user may do this.
6397 may not exit successful, since most systems
6402 .Fl f\fR errors are ignored.
6405 Removes all variables whose names match
6407 , unless they are read-only.
6408 `unset *' thus removes all variables unless they are read-only;
6410 It is not an error for nothing to be
6413 .B unsetenv \fIpattern
6414 Removes all environment variables whose names match
6416 `unsetenv *' thus removes all environment variables;
6418 It is not an error for nothing to be
6427 Without arguments, prints
6451 The shell waits for all background jobs.
6452 If the shell is interactive, an
6453 interrupt will disrupt the wait and cause the shell to print the names and job
6454 numbers of all outstanding jobs.
6459 Sets the universe to
6464 An alternate name for the
6466 builtin command (q.v.).
6467 Available only if the shell was so compiled;
6475 Reports all known instances of
6477 , including aliases, builtins and
6484 Displays the command that will be executed by the shell after substitutions,
6487 The builtin command is just like
6489 (1), but it correctly reports
6491 aliases and builtins and is 10 to 100 times faster.
6503 Executes the commands between the
6509 (an expression, as described under
6516 must appear alone on their input lines.
6520 may be used to terminate or continue the
6522 If the input is a terminal, the user is prompted the first time
6523 through the loop as with
6526 .Ss "Special aliases (+)"
6527 If set, each of these aliases executes automatically at the indicated time.
6528 They are all initially undefined.
6531 Runs when the shell wants to ring the terminal bell.
6534 Runs after every change of working directory.
6535 For example, if the user is
6536 working on an X window system using
6538 (1) and a re-parenting window
6539 manager that supports title bars such as
6544 > alias cwdcmd 'echo \-n "^[]2;${HOST}:$cwd ^G"'
6546 then the shell will change the title of the running
6549 to be the name of the host, a colon, and the full current working directory.
6550 A fancier way to do that is
6552 > alias cwdcmd 'echo \-n "^[]2;${HOST}:$cwd^G^[]1;${HOST}^G"'
6554 This will put the hostname and working directory on the title bar but
6555 only the hostname in the icon manager menu.
6565 may cause an infinite loop.
6566 It is the author's opinion that anyone doing
6567 so will get what they deserve.
6571 Runs before each command gets executed, or when the command changes state.
6574 , but it does not print builtins.
6577 > alias jobcmd 'echo \-n "^[]2\e;\e!#:q^G"'
6581 will put the command string in the xterm title bar.
6588 The command name for which help
6589 is sought is passed as sole argument.
6590 For example, if one does
6593 > alias helpcommand '\e!:1 --help'
6595 then the help display of the command itself will be invoked, using the GNU
6596 help calling convention.
6597 Currently there is no easy way to account for various calling conventions (e.g.,
6600 ), except by using a table of many commands.
6607 This provides a convenient means for
6608 checking on common but infrequent changes such as new mail.
6615 > alias periodic checknews
6619 (1) program runs every 30 minutes.
6624 is unset or set to 0,
6631 Runs just before each prompt is printed.
6632 For example, if one does
6639 (1) runs just before the shell prompts for each command.
6640 There are no limits on what
6642 can be set to do, but discretion
6647 Runs before each command gets executed.
6650 > alias postcmd 'echo \-n "^[]2\e;\e!#:q^G"'
6654 will put the command string in the xterm title bar.
6658 Specifies the interpreter for executable scripts which do not themselves
6659 specify an interpreter.
6660 The first word should be a full path name to the
6661 desired interpreter (e.g.,
6664 .Sq /usr/local/bin/tcsh
6666 .Ss "Special shell variables"
6667 The variables described in this section have special meaning to the shell.
6696 startup; they do not change thereafter unless changed by the user.
6708 The shell synchronizes
6715 with the environment variables of the same names:
6716 whenever the environment variable changes the shell changes the corresponding
6717 shell variable to match (unless the shell variable is read-only) and vice
6723 have identical meanings, they
6724 are not synchronized in this manner, and that the shell automatically
6725 converts between the different formats of
6731 If set, filename completion adds
6733 to the end of directories and a space
6734 to the end of normal files when they are matched exactly.
6740 's autolock feature uses its value instead of
6741 the local username for kerberos authentication.
6744 If set, all times are shown in 12-hour AM/PM format.
6747 This variable selects what is propagated to the value of the
6749 variable. For more information see the description of the
6754 The arguments to the shell.
6755 Positional parameters are taken from
6763 Set by default, but usually empty in interactive shells.
6765 .B autocorrect \fR(+)
6768 editor command is invoked automatically before
6769 each completion attempt.
6771 .B autoexpand \fR(+)
6774 editor command is invoked automatically
6775 before each completion attempt. If this is set to
6778 only history will be expanded and a second completion will expand filenames.
6781 If set, possibilities are listed after an ambiguous completion.
6784 , possibilities are listed only when no new
6785 characters are added by completion.
6787 .B autologout \fR(+)
6788 The first word is the number of minutes of inactivity before automatic
6790 The optional second word is the number of minutes of inactivity
6791 before automatic locking.
6792 When the shell automatically logs out, it prints
6800 When the shell automatically locks, the user is required to enter his password
6801 to continue working.
6802 Five incorrect attempts result in automatic logout.
6805 (automatic logout after 60 minutes, and no locking) by default
6806 in login and superuser shells, but not if the shell thinks it is running
6807 under a window system (i.e., the
6809 environment variable is set),
6810 the tty is a pseudo-tty (pty) or the shell was not so compiled (see the
6819 .B autorehash \fR(+)
6820 If set, the internal hash table of the contents of the directories in the
6822 variable will be recomputed if a command is not found in the hash
6824 In addition, the list of available commands will be rebuilt for each
6825 command completion or spelling correction attempt if set to
6828 `correct' respectively; if set to
6830 , this will be done for both
6833 .B backslash_quote \fR(+)
6835 If set, backslashes (`\e') always quote
6842 complex quoting tasks easier, but it can cause syntax errors in
6847 The file name of the message catalog.
6850 as a message catalog instead of
6855 A list of directories in which
6858 subdirectories if they aren't found in the current directory.
6863 requires a directory
6865 , and will not go to the
6867 directory if it's omitted.
6868 This is set by default.
6871 If set, it enables color display for the builtin \fBls\-F\fR and it passes
6872 .Fl \-color=auto\fR to
6874 Alternatively, it can be set to only
6877 to enable color to only one command.
6879 it to nothing is equivalent to setting it to \fB(ls\-F ls)\fR.
6882 If set, it enables color escape sequence for NLS message files.
6883 And display colorful NLS messages.
6886 If set, the command which was passed to the shell with the
6890 .B compat_expr \fR(+)
6891 If set, the shell will evaluate expressions right to left, like the original
6897 , the completion becomes case insensitive.
6900 , completion ignores case and considers
6901 hyphens and underscores to be equivalent; it will also treat
6902 periods, hyphens and underscores (`.',
6910 , completion matches uppercase and underscore
6911 characters explicitly and matches lowercase and hyphens in a
6912 case-insensitive manner; it will treat periods, hyphens and underscores
6916 If set to a list of commands, the shell will continue the listed
6917 commands, instead of starting a new one.
6919 .B continue_args \fR(+)
6920 Same as continue, but the shell will execute:
6923 echo \`pwd\` $argv > ~/.<cmd>_pause; %<cmd>
6929 , commands are automatically spelling-corrected.
6932 , commands are automatically completed.
6935 , the entire command line is corrected.
6937 .B csubstnonl \fR(+)
6938 If set, newlines and carriage returns in command substitution are
6943 The full pathname of the current directory.
6956 th directory from the directory
6957 stack rather than rotating it to the top.
6960 The default location in which
6971 is normally sourced before
6981 An array of all the directories on the directory stack.
6982 `$dirstack[1]' is the current working directory,
6984 the first directory on the stack, etc.
6985 Note that the current working directory is
6990 directory stack substitutions, etc.
6991 One can change the stack arbitrarily by setting
6994 but the first element (the current working directory) is always correct.
7002 Has an effect iff 'dspm' is listed as part of the
7007 , it enables display and editing EUC-kanji(Japanese) code.
7010 , it enables display and editing Shift-JIS(Japanese) code.
7013 , it enables display and editing Big5(Chinese) code.
7016 , it enables display and editing Utf8(Unicode) code.
7017 If set to the following format, it enables display and editing of original
7018 multi-byte code format:
7021 > set dspmbyte = 0000....(256 bytes)....0000
7026 Each character of 256 characters
7027 corresponds (from left to right) to the ASCII codes 0x00, 0x01, ... 0xff.
7030 .\" (position in this table?)
7031 is set to number 0,1,2 and 3.
7032 Each number has the following meaning:
7034 0 ... not used for multi-byte characters.
7036 1 ... used for the first byte of a multi-byte character.
7038 2 ... used for the second byte of a multi-byte character.
7040 3 ... used for both the first byte and second byte of a multi-byte character.
7041 .\" SHK: I tried my best to get the following to be grammatically correct.
7042 .\" However, I still don't understand what's going on here.
7044 .\" following example, there are three bytes, but the text seems to refer to
7045 .\" each nybble as a character.
7046 What's going on here? It this 3-byte code
7047 .\" in the table? The text above seems to imply that there are 256
7048 .\" characters/bytes in the table.
7049 If I get some more info on this (perhaps
7050 .\" a complete example), I could fix the text to be grammatically correct.
7051 .\" (steve.kelem@xilinx.com 1999/09/13)
7057 , the first character (means 0x00 of the ASCII code) and
7058 second character (means 0x01 of ASCII code) are set to
7061 used for multi-byte characters.
7062 The 3rd character (0x02) is set to '1',
7063 indicating that it is used for the first byte of a multi-byte character.
7064 The 4th character(0x03) is set '3'.
7065 It is used for both the first byte and
7066 the second byte of a multi-byte character.
7067 The 5th and 6th characters
7068 (0x04,0x05) are set to '2', indicating that they are used for the second
7069 byte of a multi-byte character.
7071 The GNU fileutils version of ls cannot display multi-byte
7072 filenames without the -N ( --literal ) option.
7074 this version, set the second word of dspmbyte to "ls".
7076 example, "ls-F -l" cannot display multi-byte filenames.
7080 This variable can only be used if KANJI and DSPMBYTE has been defined at
7087 removes any instances of
7089 from the stack before pushing it onto the stack.
7092 If set, each command with its arguments is echoed just before it is
7094 For non-builtin commands all expansions occur before
7096 Builtin commands are echoed before command and filename
7097 substitution, because these substitutions are then done selectively.
7099 .Fl x\fR command line option.
7101 .B echo_style \fR(+)
7111 Don't echo a newline if the first argument is
7117 Recognize backslashed escape sequences in echo strings.
7122 flag and backslashed escape sequences; the default
7130 Set by default to the local system default.
7131 The BSD and System V
7132 options are described in the
7134 (1) man pages on the appropriate
7139 If set, the command-line editor is used.
7140 Set by default in interactive
7144 A list of command names for the
7146 editor command to match.
7152 environment variables will be used instead.
7159 prompt sequences (see the
7161 shell variable) indicate skipped directories with an ellipsis (`...')
7166 The user's effective user ID.
7169 The first matching passwd entry name corresponding to the effective user ID.
7172 Lists file name suffixes to be ignored by completion.
7177 , completion is always used and this variable is ignored
7180 is unset, then the traditional
7185 , filename completion is used.
7188 The user's real group ID.
7191 If set, wild-card glob patterns will match files and directories beginning
7204 file glob patterns will match any string of
7205 characters including
7207 traversing any existing sub-directories.
7209 `ls **.c' will list all the .c files in the current directory tree).
7210 If used by itself, it will match zero or more sub-directories
7212 .Sq ls /usr/include/**/time.h
7213 will list any file named
7215 in the /usr/include directory tree; whereas
7216 .Sq ls /usr/include/**time.h
7217 will match any file in the /usr/include directory tree ending in
7220 To prevent problems with recursion, the
7222 glob-pattern will not
7223 descend into a symbolic link containing a directory.
7229 The user's group name.
7232 If set, the incremental search match (in
7236 ) and the region between the mark and the cursor are
7237 highlighted in reverse video.
7239 Highlighting requires more frequent terminal writes, which introduces extra
7240 overhead. If you care about terminal performance, you may want to leave this
7244 A string value determining the characters used in \fBHistory
7245 substitution\fR (q.v.).
7246 The first character of its value is used as
7247 the history substitution character, replacing the default character
7249 The second character of its value replaces the character
7252 quick substitutions.
7255 Controls handling of duplicate entries in the history list.
7257 `all' only unique history events are entered in the history list.
7261 and the last history event is the same as the current
7262 command, then the current command is not entered in the history.
7266 and the same event is found in the history list, that
7267 old event gets erased and the current one gets inserted.
7271 options renumber history events so there are no gaps.
7274 The default location in which
7285 useful when sharing the same home directory between different machines,
7286 or when saving separate histories on different terminals.
7289 is normally sourced before
7299 If set, builtin and editor commands and the
7302 use the literal (unexpanded) form of lines in the history list.
7305 .Va toggle-literal-history
7309 The first word indicates the number of history events to save.
7311 optional second word (+) indicates the format in which history is
7312 printed; if not given,
7315 The format sequences
7316 are described below under
7318 ; note the variable meaning of
7325 Initialized to the home directory of the invoker.
7330 refers to this variable.
7333 If set to the empty string or
7335 and the input device is a terminal,
7338 command (usually generated by the user by typing
7339 `^D' on an empty line) causes the shell to print `Use "exit" to leave
7340 tcsh.' instead of exiting.
7341 This prevents the shell from accidentally
7343 Historically this setting exited after 26 successive
7344 EOF's to avoid infinite loops.
7357 is used, i.e., the shell exits on a
7361 .B implicitcd \fR(+)
7362 If set, the shell treats a directory name typed as a command as though
7363 it were a request to change to that directory.
7367 the change of directory is echoed to the standard output.
7369 is inhibited in non-interactive shell scripts, or for command strings
7370 with more than one word.
7371 Changing directory takes precedence over
7372 executing a like-named command, but it is done after alias
7374 Tilde and variable expansions work as expected.
7381 , puts the editor into that input mode
7382 at the beginning of each line.
7385 Controls handling of duplicate entries in the kill ring.
7387 `all' only unique strings are entered in the kill ring.
7389 `prev' and the last killed string is the same as the current killed
7390 string, then the current string is not entered in the ring.
7394 and the same string is found in the kill ring, the old
7395 string is erased and the current one is inserted.
7398 Indicates the number of killed strings to keep in memory.
7402 If unset or set to less than
7404 , the shell will only
7405 keep the most recently killed string.
7406 Strings are put in the killring by the editor commands that delete
7407 (kill) strings of text, e.g.
7408 .Va backward-delete-word
7411 , etc, as well as the
7412 .Va copy-region-as-kill
7416 editor command will yank the most recently killed string
7417 into the command-line, while
7422 can be used to yank earlier killed strings.
7431 , or any combination thereof (e.g.,
7434 are used as flags to \fIls\-F\fR, making it act like
7439 or a combination (e.g.,
7444 files (even if they start with a
7453 sorts across instead of down.
7454 If the second word of
7456 is set, it is used as the path to
7460 If set, all jobs are listed when a job is suspended.
7464 the listing is in long format.
7467 If set, the \fIls\-F\fR builtin command shows the type of file to which
7468 each symbolic link points.
7471 The maximum number of items which the
7474 will list without asking first.
7476 .B listmaxrows \fR(+)
7477 The maximum number of rows of items which the
7480 command will list without asking first.
7483 Set by the shell if it is a login shell.
7484 Setting or unsetting it
7485 within a shell has no effect.
7492 before a normal logout,
7495 an automatic logout, and
7497 if the shell was killed by a hangup
7506 A list of files and directories to check for incoming mail, optionally
7507 preceded by a numeric word.
7508 Before each prompt, if 10 minutes have
7509 passed since the last check, the shell checks each file and says `You
7510 have new mail.' (or, if
7512 contains multiple files, `You have
7515 .') if the filesize is greater than zero in size
7516 and has a modification time greater than its access time.
7521 If you are in a login shell, then no mail file is reported unless it has
7522 been modified after the time the shell has started up, to prevent
7523 redundant notifications.
7524 Most login programs will tell you whether or not
7525 you have mail when you log in.
7527 If a file specified in
7529 is a directory, the shell will count each
7530 file within that directory as a separate message, and will report `You have
7538 This functionality is provided primarily for those systems which store mail
7539 in this manner, such as the Andrew Mail System.
7541 If the first word of
7543 is numeric it is taken as a different mail
7544 checking interval, in seconds.
7546 Under very rare circumstances, the shell may report
7550 .Sq You have new mail.
7556 , completion never beeps.
7559 , it beeps only when there is no match.
7562 , it beeps when there are multiple matches.
7565 , it beeps when there is one exact and other longer matches.
7571 If set, beeping is completely disabled.
7576 If set, restrictions are placed on output redirection to insure that files
7577 are not accidentally destroyed and that
7579 redirections refer to existing
7580 files, as described in the
7585 If set, disable the printing of
7590 specifiers at the change of hour.
7594 .Va Filename substitution
7596 .Va Directory stack substitution
7597 (q.v.) are inhibited.
7598 This is most useful in shell scripts which do not deal
7599 with filenames, or after a list of filenames has been obtained and further
7600 expansions are not desirable.
7603 If set and the shell supports Kanji (see the
7606 it is disabled so that the meta key can be used.
7610 .Va Filename substitution
7612 .Va Directory stack substitution
7613 (q.v.) which does not match any
7614 existing files is left untouched rather than causing an error.
7615 It is still an error for the substitution to be
7618 still gives an error.
7621 A list of directories (or glob-patterns which match directories; see
7622 .Va Filename substitution
7623 ) that should not be
7626 completion operation.
7627 This is usually used to exclude directories which
7628 take too much time to
7634 If set, the shell announces job completions asynchronously.
7635 The default is to present job completions just before printing a prompt.
7638 The user's real organization ID.
7642 The old working directory, equivalent to the
7655 If set, enable the printing of padding '0' for hours, in 24 and 12 hour
7657 E.G.: 07:45:42 vs. 7:45:42.
7660 To retain compatibily with older versions numeric variables starting with
7661 0 are not interpreted as octal. Setting this variable enables proper octal
7665 A list of directories in which to look for executable commands.
7666 A null word specifies the current directory.
7669 variable then only full path names will execute.
7671 is set by the shell at startup from the
7676 does not exist, to a system-dependent default
7678 .Sq (/usr/local/bin /usr/bsd /bin /usr/bin .)
7684 depending on how it was compiled; see the
7687 A shell which is given neither the
7690 hashes the contents of the directories in
7698 If one adds a new command to a directory in
7701 is active, one may need to do a
7703 for the shell to find it.
7705 .B printexitvalue \fR(+)
7706 If set and an interactive program exits with a non-zero status, the shell
7712 The string which is printed before reading each command from the terminal.
7714 may include any of the following formatting sequences (+), which
7715 are replaced by the given information:
7721 The current working directory.
7724 The current working directory, but with one's home directory
7727 and other users' home directories represented by
7729 .Va Filename substitution
7730 `~user' substitution
7731 happens only if the shell has already used
7735 in the current session.
7742 The trailing component of the current working directory, or
7744 trailing components if a digit
7751 , the number of skipped components precede
7752 the trailing component(s) in the format
7758 shell variable is set, skipped components
7759 are represented by an ellipsis so the whole becomes
7761 `~' substitution is done as in
7766 is ignored when counting trailing components.
7769 Like %c, but without
7774 The current history event number.
7780 The hostname up to the first
7784 Start (stop) standout mode.
7787 Start (stop) boldfacing mode.
7790 Start (stop) underline mode.
7793 The time of day in 12-hour AM/PM format.
7798 , but in 24-hour format (but see the
7805 time of day in 12-hour AM/PM format, with seconds.
7810 , but in 24-hour format (but see the
7834 The effective user name.
7873 Clears from the end of the prompt to end of the display or the end of the line.
7876 Expands the shell or environment variable name immediately after the
7880 `>' (or the first character of the
7885 (or the second character of
7895 as a literal escape sequence.
7896 It should be used only to change terminal attributes and
7897 should not move the cursor location.
7899 cannot be the last sequence in
7903 The return code of the command executed just before the prompt.
7908 , the status of the parser.
7911 , the corrected string.
7914 , the history string.
7925 are available in only
7926 eight-bit-clean shells; see the
7930 The bold, standout and underline sequences are often used to distinguish a
7934 > set prompt = "%m [%h] %B[%@]%b [%/] you rang? "
7938 [/usr/accts/sys] you rang? _
7955 on the change of hour (i.e,
7962 in interactive shells.
7966 The string with which to prompt in
7971 after lines ending in
7973 The same format sequences may be used as in
7976 note the variable meaning of
7980 in interactive shells.
7983 The string with which to prompt when confirming automatic spelling correction.
7984 The same format sequences may be used as in
7987 note the variable meaning of
7990 .Sq CORRECT>%R (y|n|e|a)?
7991 in interactive shells.
7993 .B promptchars \fR(+)
7994 If set (to a two-character string), the
7996 formatting sequence in the
7998 shell variable is replaced with the first character for
7999 normal users and the second character for the superuser.
8001 .B pushdtohome \fR(+)
8004 without arguments does
8009 .B pushdsilent \fR(+)
8014 do not print the directory stack.
8017 If set, completion completes on an exact match even if a longer match is
8020 .B recognize_only_executables \fR(+)
8021 If set, command listing displays only files in the path that are
8026 If set, the user is prompted before
8031 The string to print on the right-hand side of the screen (after
8032 the command input) when the prompt is being displayed on the left.
8033 It recognizes the same formatting characters as
8035 It will automatically disappear and reappear as necessary, to ensure that
8036 command input isn't obscured, and will appear only if the prompt,
8037 command input, and itself will fit together on the first line.
8042 will be printed after
8043 the prompt and before the command input.
8046 If set, the shell does
8049 If the first word is set to a number, at most that many directory stack
8053 If set, the shell does
8056 If the first word is set to a number, at most that many lines are saved.
8057 (The number should be less than or equal to the number
8060 if it is set to greater than the number of
8064 entries will be saved)
8065 If the second word is set to
8067 , the history list is merged with
8068 the existing history file instead of replacing it (if there is one) and
8069 sorted by time stamp and the most recent events are retained.
8070 If the second word of
8074 and the third word is set to
8075 `lock', the history file update will be serialized with other shell sessions
8076 that would possibly like to merge history at exactly the same time. (+)
8079 The format in which the
8081 builtin command prints scheduled events;
8085 The format sequences are described above under
8088 note the variable meaning of
8092 The file in which the shell resides.
8093 This is used in forking
8094 shells to interpret files which have execute bits set, but
8095 which are not executable by the system.
8096 (See the description
8098 .Va Builtin and non-builtin command execution
8099 .) Initialized to the
8100 (system-dependent) home of the shell.
8103 The number of nested shells.
8104 Reset to 1 in login shells.
8109 The exit status from the last command or backquote expansion, or any
8110 command in a pipeline is propagated to
8116 This default does not match what POSIX mandates (to return the
8117 status of the last command only). To match the POSIX behavior, you need
8124 variable is unset, the exit status of a pipeline
8125 is determined only from the last command in the pipeline, and the exit
8126 status of a backquote expansion is
8131 If a command terminated abnormally, then 0200 is added to the status.
8132 Builtin commands which fail return exit status
8135 commands return status
8140 Can be set to several different values to control symbolic link (`symlink')
8146 , whenever the current directory changes to a directory
8147 containing a symbolic link, it is expanded to the real name of the directory
8148 to which the link points.
8149 This does not work for the user's home directory;
8154 , the shell tries to construct a current directory
8155 relative to the current directory before the link was crossed.
8158 ing through a symbolic link and then
8161 returns one to the original directory.
8162 This affects only builtin commands
8163 and filename completion.
8167 , the shell tries to fix symbolic links by actually expanding
8168 arguments which look like path names.
8169 This affects any command, not just
8171 Unfortunately, this does not work for hard-to-recognize filenames,
8172 such as those embedded in command options.
8173 Expansion may be prevented by
8175 While this setting is usually the most convenient, it is sometimes
8176 misleading and sometimes confusing when it fails to recognize an argument
8177 which should be expanded.
8178 A compromise is to use
8183 (bound by default to ^X-n) when necessary.
8185 Some examples are in order.
8186 First, let's set up some play directories:
8190 > mkdir from from/src to
8192 > ln \-s from/src to/dst
8194 Here's the behavior with
8198 > cd /tmp/to/dst; echo $cwd
8206 here's the behavior with
8212 > cd /tmp/to/dst; echo $cwd
8220 here's the behavior with
8226 > cd /tmp/to/dst; echo $cwd
8234 and here's the behavior with
8239 > cd /tmp/to/dst; echo $cwd
8247 > cd /tmp/to/dst; echo $cwd
8251 > cd ".."; echo $cwd
8265 expansion 1) works just like
8270 , 2) is prevented by quoting, and 3) happens before
8271 filenames are passed to non-builtin commands.
8275 The version number of the shell in the format
8280 is the major release number,
8292 .Va Startup and shutdown
8295 If set to a number, then the
8297 builtin (q.v.) executes automatically
8298 after each command which takes more than that many CPU seconds.
8299 If there is a second word, it is used as a format string for the output
8303 (u) The following sequences may be used in the
8310 The time the process spent in user mode in cpu seconds.
8313 The time the process spent in kernel mode in cpu seconds.
8316 The elapsed (wall clock) time in seconds.
8319 The CPU percentage computed as (%U + %S) / %E.
8322 Number of times the process was swapped.
8325 The average amount in (shared) text space used in Kbytes.
8328 The average amount in (unshared) data/stack space used in Kbytes.
8331 The total space used (%X + %D) in Kbytes.
8334 The maximum memory the process had in use at any time in Kbytes.
8337 The number of major page faults (page needed to be brought from disk).
8340 The number of minor page faults.
8343 The number of input operations.
8346 The number of output operations.
8349 The number of socket messages received.
8352 The number of socket messages sent.
8355 The number of signals received.
8358 The number of voluntary context switches (waits).
8361 The number of involuntary context switches.
8364 Only the first four sequences are supported on systems without BSD resource
8366 The default time format is
8367 .Sq %Uu %Ss %E %P %X+%Dk %I+%Oio %Fpf+%Ww
8369 systems that support resource usage reporting and
8372 systems that do not.
8374 Under Sequent's DYNIX/ptx, %X, %D, %K, %r and %s are not
8375 available, but the following additional sequences are:
8380 The number of system calls performed.
8383 The number of pages which are zero-filled on demand.
8386 The number of times a process's resident set size was increased by the kernel.
8389 The number of times a process's resident set size was decreased by the kernel.
8392 The number of read system calls performed.
8395 The number of write system calls performed.
8398 The number of reads from raw disk devices.
8401 The number of writes to raw disk devices.
8404 and the default time format is
8405 .Sq %Uu %Ss %E %P %I+%Oio %Fpf+%Ww
8406 Note that the CPU percentage can be higher than 100% on multi-processors.
8410 The period, in minutes, between executions of the
8415 The name of the tty, or empty if not attached to one.
8418 The user's real user ID.
8421 The user's login name.
8424 If set, causes the words of each
8425 command to be printed, after history substitution (if any).
8427 .Fl v\fR command line option.
8430 The version ID stamp.
8431 It contains the shell's version number (see
8434 origin, release date, vendor, operating system and machine (see
8440 ) and a comma-separated
8441 list of options which were set at compile time.
8442 Options which are set by default in the distribution are noted.
8448 The shell is eight bit clean; default
8451 The shell is not eight bit clean
8454 The shell is multibyte encoding clean (like UTF-8)
8457 The system's NLS is used; default for systems with NLS
8460 Login shells execute
8462 before instead of after
8466 before instead of after
8474 for security; default
8483 (1)\-style editing is the default rather than
8488 Login shells drop DTR when exiting
8496 is an alternate name for
8504 Kanji is used if appropriate according to locale settings,
8507 shell variable is set
8516 .Sq #!<program> <args>
8517 convention is emulated when executing shell scripts
8522 builtin is available
8525 The shell attempts to set the
8527 environment variable
8530 The shell verifies your password with the kerberos server if local
8531 authentication fails.
8534 shell variable or the
8536 environment variable override your local username if set.
8539 An administrator may enter additional strings to indicate differences
8540 in the local version.
8545 If unset, various key bindings change behavior to be more
8548 word boundaries are determined by
8550 versus other characters.
8552 If set, various key bindings change behavior to be more
8555 word boundaries are determined by
8558 versus other characters;
8559 cursor behavior depends upon current vi mode (command, delete, insert, replace).
8561 This variable is unset by
8571 may be explicitly set or unset by the user after those
8573 operations if required.
8576 .B visiblebell \fR(+)
8577 If set, a screen flash is used rather than the audible bell.
8582 A list of user/terminal pairs to watch for logins and logouts.
8583 If either the user is
8585 all terminals are watched for the given user
8591 watches all users and terminals.
8595 set watch = (george ttyd1 any console $user any)
8597 reports activity of the user
8599 on ttyd1, any user on the console, and
8600 oneself (or a trespasser) on any terminal.
8602 Logins and logouts are checked every 10 minutes by default, but the first
8605 can be set to a number to check every so many minutes.
8608 set watch = (1 any any)
8610 reports any login/logout once every minute.
8611 For the impatient, the
8613 builtin command triggers a
8617 are reported (as with the
8625 shell variable controls the format of
8631 The format string for
8634 The following sequences
8635 are replaced by the given information:
8641 The name of the user who logged in/out.
8644 The observed action, i.e.,
8654 The terminal (tty) on which the user logged in/out.
8657 The full hostname of the remote host, or
8659 if the login/logout was
8660 from the local host.
8663 The hostname of the remote host up to the first
8665 The full name is printed if it is an IP address or an X Window System display.
8668 %M and %m are available on only systems that store the remote hostname in
8671 .Sq %n has %a %l from %m.
8675 which don't store the remote hostname.
8679 A list of non-alphanumeric characters to be considered part of a word by the
8683 etc., editor commands.
8684 If unset, the default value is determined based on the state of
8691 is used as the default;
8696 is used as the default.
8705 The number of columns in the terminal.
8707 .Va Terminal management
8710 Used by X Window System (see
8713 If set, the shell does not set
8718 The pathname to a default editor.
8721 editor command if the
8724 shell variable is unset.
8727 environment variable.
8740 Initialized to the name of the machine on which the shell
8741 is running, as determined by the
8746 Initialized to the type of machine on which the shell
8747 is running, as determined at compile time.
8748 This variable is obsolete and
8749 will be removed in a future version.
8752 A colon-separated list of directories in which the
8755 command looks for command documentation.
8758 Gives the preferred character environment.
8760 .Va Native Language System support
8763 If set, only ctype character handling is changed.
8765 .Va Native Language System support
8768 The number of lines in the terminal.
8770 .Va Terminal management
8773 The format of this variable is reminiscent of the
8775 file format; a colon-separated list of expressions of the form
8780 " is a two-character variable name.
8782 variables with their associated defaults are:
8789 Normal (non-filename) text
8819 Missing file (defaults to fi)
8822 Orphaned symbolic link (defaults to ln)
8831 End code (replaces lc+no+rc)
8835 You need to include only the variables you want to change from
8838 File names can also be colorized based on filename extension.
8839 This is specified in the
8841 variable using the syntax
8843 For example, using ISO 6429 codes, to color
8844 all C\-language source files blue you would specify
8846 This would color all files ending in
8850 Control characters can be written either in C\-style\-escaped
8851 notation, or in stty\-like ^\-notation.
8852 The C\-style notation
8855 for Escape, \fB\_\fR for a normal space character,
8862 can be used to override the default interpretation of
8871 Each file will be written as
8882 code is undefined, the sequence
8886 will be used instead.
8887 This is generally more convenient
8888 to use, but less general.
8889 The left, right and end codes are
8890 provided so you don't have to type common parts over and over
8891 again and to support weird terminals; you will generally not
8892 need to change them at all unless your terminal does not use
8893 ISO 6429 color sequences but a different system.
8895 If your terminal does use ISO 6429 color codes, you can
8896 compose the type codes (i.e., all except the
8903 codes) from numerical commands separated by semicolons.
8905 most common commands are:
8911 to restore default color
8923 for black foreground
8929 for green foreground
8932 for yellow (or brown) foreground
8938 for purple foreground
8944 for white (or gray) foreground
8947 for black background
8953 for green background
8956 for yellow (or brown) background
8962 for purple background
8968 for white (or gray) background
8972 Not all commands will work on all systems or display devices.
8974 A few terminal programs do not recognize the default end code
8976 If all text gets colorized after you do a directory
8977 listing, try changing the
8982 numerical codes for your standard fore- and background colors.
8986 The machine type (microprocessor class or machine model), as determined at compile time.
8989 If set, printable characters are not rebound to
8990 .Va self-insert-command
8992 .Va Native Language System support
8995 The operating system, as determined at compile time.
8998 A colon-separated list of directories in which to look for executables.
9001 shell variable, but in a different format.
9006 shell variable, but not synchronized to it;
9007 updated only after an actual directory change.
9009 .B REMOTEHOST \fR(+)
9010 The host from which the user has logged in remotely, if this is the case and
9011 the shell is able to determine it.
9012 Set only if the shell was so compiled;
9023 The current system type.
9032 The terminal capability string.
9034 .Va Terminal management
9042 The vendor, as determined at compile time.
9045 The pathname to a default full-screen editor.
9048 editor command if the
9051 shell variable is unset.
9054 environment variable.
9059 Read first by every shell.
9060 ConvexOS, Stellix and Intel use
9065 A/UX, AMIX, Cray and IRIX have no equivalent in
9068 but read this file in
9071 Solaris 2.x does not have it either, but
9078 Read by login shells after
9080 ConvexOS, Stellix and Intel use
9088 A/UX, AMIX, Cray and IRIX use
9092 Read by every shell after
9097 Read by every shell, if
9116 Read by login shells after
9120 is set, but see also
9124 Read by login shells after
9128 The shell may be compiled to read
9130 before instead of after
9138 .I ~/.cshdirs \fR(+)
9139 Read by login shells after
9143 is set, but see also
9147 Read by login shells at logout.
9148 ConvexOS, Stellix and Intel use
9153 A/UX, AMIX, Cray and IRIX have no equivalent in
9156 but read this file in
9159 Solaris 2.x does not have it either, but
9166 Read by login shells at logout after
9171 Used to interpret shell scripts not starting with a
9179 Source of home directories for
9184 The order in which startup files are read may differ if the shell was so
9186 .Va Startup and shutdown
9190 .Sh "NEW FEATURES (+)"
9191 This manual describes
9196 users will want to pay special attention to
9200 A command-line editor, which supports
9205 (1)\-style key bindings.
9207 .Va The command-line editor
9211 Programmable, interactive word completion and listing.
9213 .Sx Completion and listing
9220 .Va Spelling correction
9221 (q.v.) of filenames, commands and variables.
9224 (q.v.) which perform other useful functions in the middle of
9225 typed commands, including documentation lookup
9227 quick editor restarting
9228 .Va ( run-fg-editor )
9231 .Va ( which-command ).
9233 An enhanced history mechanism.
9234 Events in the history list are time-stamped.
9237 command and its associated shell variables,
9238 the previously undocumented
9240 event specifier and new modifiers
9242 .Va History substitution
9247 .Va history-search-*
9253 .Va toggle-literal-history
9259 Enhanced directory parsing and directory stack handling.
9268 commands and their associated
9269 shell variables, the description of
9270 .Va Directory stack substitution
9280 .Va normalize-command
9285 Negation in glob-patterns.
9287 .Va Filename substitution
9290 .Va File inquiry operators
9293 builtin which uses them.
9296 .Va Automatic, periodic and timed events
9298 scheduled events, special aliases, automatic logout and terminal locking,
9299 command timing and watching for logins and logouts.
9301 Support for the Native Language System
9303 .Va Native Language System support
9307 .Va OS variant support
9311 and system-dependent file locations (see
9315 Extensive terminal-management capabilities.
9317 .Va Terminal management
9319 New builtin commands including
9333 New variables that make useful information easily available to the shell.
9350 shell variables and the
9363 A new syntax for including useful information in the prompt string
9367 and special prompts for loops and spelling correction
9374 Read-only variables.
9376 .Va Variable substitution
9378 When a suspended command is restarted, the shell prints the directory
9379 it started in if this is different from the current directory.
9381 be misleading (i.e., wrong) as the job may have changed directories internally.
9383 Shell builtin functions are not stoppable/restartable.
9387 are also not handled gracefully when stopping is
9391 , the shell will then immediately execute
9393 This is especially noticeable if this expansion results from an
9395 It suffices to place the sequence of commands in ()'s to force it
9396 to a subshell, i.e.,
9399 Control over tty output after processes are started is primitive; perhaps
9400 this will inspire someone to work on a good virtual terminal interface.
9401 In a virtual terminal interface much more interesting things could be
9402 done with output control.
9404 Alias substitution is most often used to clumsily simulate shell procedures;
9405 shell procedures should be provided rather than aliases.
9407 Control structures should be parsed rather than being recognized as
9409 This would allow control commands to be placed anywhere,
9412 , and to be used with
9419 doesn't ignore here documents when looking for its
9422 It should be possible to use the
9424 modifiers on the output of command
9427 The screen update for lines longer than the screen width is very poor
9428 if the terminal cannot move the cursor up (i.e., terminal type
9435 don't need to be environment variables.
9437 Glob-patterns which do not use
9447 are not negated correctly.
9449 The single-command form of
9451 does output redirection even if
9452 the expression is false and the command is not executed.
9454 \fIls\-F\fR includes file identification characters when sorting filenames
9455 and does not handle control characters in filenames well.
9459 Command substitution supports multiple commands and conditions, but not
9464 Report bugs at https://bugs.astron.com/, preferably with fixes.
9466 help maintain and test tcsh, add yourself to the mailing list in
9467 https://mailman.astron.com/.
9469 on a line by itself in the body.
9471 In 1964, DEC produced the PDP-6.
9472 The PDP-10 was a later re-implementation.
9474 was re-christened the DECsystem-10 in 1970 or so when DEC brought out the
9475 second model, the KI10.
9477 TENEX was created at Bolt, Beranek & Newman (a Cambridge, Massachusetts
9479 1972 as an experiment in demand-paged virtual memory operating systems.
9481 built a new pager for the DEC PDP-10 and created the OS to go with it.
9483 extremely successful in academia.
9485 In 1975, DEC brought out a new model of the PDP-10, the KL10; they intended to
9486 have only a version of TENEX, which they had licensed from BBN, for the new
9488 They called their version TOPS-20 (their capitalization is trademarked).
9489 A lot of TOPS-10 users (`The OPerating System for PDP-10') objected; thus DEC
9490 found themselves supporting two incompatible systems on the same hardware--but
9491 then there were 6 on the PDP-11!
9493 TENEX, and TOPS-20 to version 3, had command completion
9494 via a user-code-level subroutine library called ULTCMD.
9496 moved all that capability and more into the monitor (`kernel' for you Unix
9497 types), accessed by the COMND% JSYS (`Jump to SYStem' instruction, the
9498 supervisor call mechanism [are my IBM roots also showing?]).
9500 The creator of tcsh was impressed by this feature and several others of TENEX
9501 and TOPS-20, and created a version of csh which mimicked them.
9503 The system limits argument lists to ARG_MAX characters.
9505 The number of arguments to a command which involves filename expansion is
9506 limited to 1/6th the number of characters allowed in an argument list.
9508 Command substitutions may substitute no more characters than are allowed in
9511 To detect looping, the shell restricts the number of
9513 substitutions on a single line to 20.
9515 csh(1), emacs(1), ls(1), newgrp(1), sh(1), setpath(1), stty(1), su(1),
9516 tset(1), vi(1), x(1), access(2), execve(2), fork(2), killpg(2),
9517 pipe(2), setrlimit(2), sigvec(2), stat(2), umask(2), vfork(2), wait(2),
9518 malloc(3), setlocale(3), tty(4), a.out(5), termcap(5), environ(7),
9519 termio(7), Introduction to the C Shell
9521 This manual documents tcsh 6.21.00 (Astron) 2019-05-08.
9529 J.E. Kulp, IIASA, Laxenburg, Austria
9530 Job control and directory stack features
9532 Ken Greer, HP Labs, 1981
9533 File name completion
9535 Mike Ellis, Fairchild, 1983
9536 Command name recognition/completion
9538 Paul Placeway, Ohio State CIS Dept., 1983-1993
9539 Command line editor, prompt routines, new glob syntax and numerous fixes
9542 Karl Kleinpaste, CCI 1983-4
9543 Special aliases, directory stack extraction stuff, login/logout watch,
9544 scheduled events, and the idea of the new prompt format
9546 Rayan Zachariassen, University of Toronto, 1984
9549 builtins and numerous bug fixes, modifications
9552 Chris Kingsley, Caltech
9553 Fast storage allocator routines
9555 Chris Grevstad, TRW, 1987
9561 Christos S. Zoulas, Cornell U. EE Dept., 1987-94
9562 Ports to HPUX, SVR2 and SVR3, a SysV version of getwd.c, SHORT_STRINGS support
9563 and a new version of sh.glob.c
9565 James J Dempsey, BBN, and Paul Placeway, OSU, 1988
9568 Daniel Long, NNSC, 1988
9571 Patrick Wolfe, Kuck and Associates, Inc., 1988
9575 David C Lawrence, Rensselaer Polytechnic Institute, 1989
9577 and ambiguous completion listing
9579 Alec Wolman, DEC, 1989
9580 Newlines in the prompt
9582 Matt Landau, BBN, 1989
9585 Ray Moody, Purdue Physics, 1989
9586 Magic space bar history expansion
9588 Mordechai ????, Intel, 1989
9589 printprompt() fixes and additions
9591 Kazuhiro Honda, Dept. of Computer Science, Keio University, 1989
9592 Automatic spelling correction and
9595 Per Hedeland, Ellemtel, Sweden, 1990-
9596 Various bugfixes, improvements and manual updates
9598 Hans J. Albertsson (Sun Sweden)
9606 Interrupt handling fixes
9608 Michael Fine, Digital Equipment Corp
9609 Extended key support
9611 Eric Schnoebelen, Convex, 1990
9612 Convex support, lots of
9615 save and restore of directory stack
9617 Ron Flax, Apple, 1990
9620 Dan Oscarsson, LTH Sweden, 1990
9621 NLS support and simulated NLS support for non NLS sites, fixes
9623 Johan Widen, SICS Sweden, 1990
9629 Matt Day, Sanyo Icon, 1990
9630 POSIX termio support, SysV limit fixes
9632 Jaap Vermeulen, Sequent, 1990-91
9633 Vi mode fixes, expand-line, window change fixes, Symmetry port
9635 Martin Boyer, Institut de recherche d'Hydro-Quebec, 1991
9637 beeping options, modified the history search to search for
9638 the whole string from the beginning of the line to the cursor.
9640 Scott Krotz, Motorola, 1991
9643 David Dawes, Sydney U. Australia, Physics Dept., 1991
9644 SVR4 job control fixes
9646 Jose Sousa, Interactive Systems Corp., 1991
9653 Marc Horowitz, MIT, 1991
9654 ANSIfication fixes, new exec hashing code, imake fixes,
9657 Bruce Sterling Woodcock, sterling@netcom.com, 1991-1995
9658 ETA and Pyramid port, Makefile and lint fixes,
9661 various other portability changes and bug fixes
9664 .Va complete-word-fwd
9666 .Va complete-word-back
9668 Harry C. Pulley, 1992
9671 Andy Phillips, Mullard Space Science Lab U.K., 1992
9674 Beto Appleton, IBM Corp., 1992
9675 Walking process group fixes,
9678 POSIX file tests, POSIX SIGHUP
9680 Scott Bolte, Cray Computer Corp., 1992
9683 Kaveh R. Ghazi, Rutgers University, 1992
9684 Tek, m88k, Titan and Masscomp ports and fixes.
9685 Added autoconf support.
9687 Mark Linderman, Cornell University, 1992
9690 Mika Liljeberg, liljeber@kruuna.Helsinki.FI, 1992
9693 Tim P. Starrin, NASA Langley Research Center Operations, 1993
9696 Dave Schweisguth, Yale University, 1993-4
9697 New man page and tcsh.man2html
9699 Larry Schwimmer, Stanford University, 1993
9700 AFS and HESIOD patches
9702 Luke Mewburn, RMIT University, 1994-6
9703 Enhanced directory printing in prompt,
9709 Edward Hutchins, Silicon Graphics Inc., 1996
9712 Martin Kraemer, 1997
9713 Ported to Siemens Nixdorf EBCDIC machine
9715 Amol Deshpande, Microsoft, 1997
9716 Ported to WIN32 (Windows/95 and Windows/NT); wrote all the missing library
9717 and message catalog code to interface to Windows.
9724 Bryan Dunlap, Clayton Elwell, Karl Kleinpaste, Bob Manson, Steve Romig,
9725 Diana Smetters, Bob Sutterfield, Mark Verber, Elizabeth Zwicky and all
9726 the other people at Ohio State for suggestions and encouragement
9728 All the people on the net, for putting up with,
9729 reporting bugs in, and suggesting new additions to each and every version
9731 Richard M. Alderson III, for writing the
projects / FreeBSD / FreeBSD.git / blob