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 By default history entries are displayed by printing each parsed token
1498 separated by space; thus the redirection operator
1500 will be displayed as
1502 The shell actually saves history in expanded and literal (unexpanded) forms.
1505 shell variable is set, commands that display and store
1506 history use the literal form.
1510 builtin command can print, store in a file, restore
1511 and clear the history list at any time,
1516 shell variables can be set to
1517 store the history list automatically on logout and restore it on login.
1519 History substitutions introduce words from the history list into the input
1520 stream, making it easy to repeat commands, repeat arguments of a previous
1521 command in the current command, or fix spelling mistakes in the previous
1522 command with little typing and a high degree of confidence.
1524 History substitutions begin with the character
1526 They may begin anywhere in
1527 the input stream, but they do not nest.
1530 may be preceded by a
1533 prevent its special meaning; for convenience, a
1535 is passed unchanged when it
1536 is followed by a blank, tab, newline,
1540 History substitutions also
1541 occur when an input line begins with
1543 This special abbreviation will be
1545 The characters used to signal history substitution
1549 can be changed by setting the
1553 line which contains a history substitution is printed before it is executed.
1555 A history substitution may have an
1556 .Sq event specification ,
1557 which indicates the event from which words are to be taken, a
1558 .Sq word designator ,
1559 which selects particular words from the chosen event, and/or a
1561 which manipulates the selected words.
1563 An event specification can be
1565 .Bl -tag -width XXXX -offset indent -compact
1567 A number, referring to a particular event
1569 An offset, referring to the event
1571 before the current event
1574 This should be used carefully in
1576 where there is no check for recursion.
1578 allows 10 levels of recursion.
1581 The previous event (equivalent to
1584 The most recent event whose first word begins with the string
1587 The most recent event which contains the string
1591 can be omitted if it is immediately followed by a newline.
1594 For example, consider this bit of someone's history list:
1595 .Bd -literal -offset indent
1596 9 8:30 nroff \-man wumpus.man
1597 10 8:31 cp wumpus.man wumpus.man.old
1598 11 8:36 vi wumpus.man
1599 12 8:37 diff wumpus.man.old wumpus.man
1602 The commands are shown with their event numbers and time stamps.
1603 The current event, which we haven't typed in yet, is event 13.
1609 refers to the previous event, 12.
1617 is described below).
1619 refers to event 9, which begins with
1622 also refers to event 12, which contains
1624 Without word designators or modifiers history references simply expand to the
1625 entire event, so we might type
1627 to redo the copy command or
1631 output scrolled off the top of the screen.
1633 History references may be insulated from the surrounding text with braces if
1637 would look for a command beginning with
1639 and, in this example, not find one, but
1643 .Sq vi wumpus.mandoc
1644 Even in braces, history substitutions do not nest.
1648 expands, for example,
1655 expands it to the last event beginning
1658 only completely numeric arguments are treated as event numbers.
1659 This makes it possible to recall events beginning with numbers.
1667 To select words from an event we can follow the event specification by a
1669 and a designator for the desired words.
1670 The words of an input line are
1671 numbered from 0, the first (usually command) word being 0, the second word
1672 (first argument) being 1, etc.
1673 The basic word designators are:
1675 .Bl -tag -width XXXX -offset indent -compact
1677 The first (command) word
1683 The first argument, equivalent to
1688 The word matched by an ?
1699 but returns nothing if the event contains only 1 word
1706 but omitting the last word
1710 Selected words are inserted into the command line separated by single blanks.
1713 command in the previous example might have been
1715 .Sq diff !!:1.old !!:1
1718 to select the first argument
1719 from the previous event) or
1720 .Sq diff !\-2:2 !\-2:1
1721 to select and swap the
1725 If we didn't care about the order of the
1726 `diff' we might have said
1732 command might have been written
1733 .Sq cp wumpus.man !#:1.old
1736 to refer to the current event.
1737 `!n:\- hurkle.man' would reuse the first two words from the
1741 .Sq nroff \-man hurkle.man
1745 separating the event specification from the word designator can be
1746 omitted if the argument selector begins with a
1755 command might have been
1756 .Sq diff !!^.old !!^
1759 .Sq diff !!$.old !!$
1765 an argument selector beginning with
1767 will be interpreted as an event
1770 A history reference may have a word designator but no event specification.
1771 It then references the previous command.
1774 example, we could have said simply `diff
1775 !^.old !^' or, to get the arguments in the opposite order, just
1778 The word or words in a history reference can be edited, or
1781 by following it with one or more modifiers, each preceded by a
1784 .Bl -tag -width XXXXXX -offset indent -compact
1786 Remove a trailing pathname component, leaving the head.
1788 Remove all leading pathname components, leaving the tail.
1790 Remove a filename extension
1792 leaving the root name.
1794 Remove all but the extension.
1796 Uppercase the first lowercase letter.
1798 Lowercase the first uppercase letter.
1805 is simply a string like
1807 , not a regular expression as in
1811 Any character may be used as the delimiter in place of
1815 can be used to quote the delimiter inside
1834 from a previous substitution or the
1836 from a previous search or event number in event specification is used.
1837 The trailing delimiter may be omitted if it is immediately followed by a
1840 Repeat the previous substitution.
1842 Apply the following modifier once to each word.
1844 Apply the following modifier as many times as possible to a single word.
1848 can be used together to apply a modifier globally.
1851 modifier, only the patterns contained in the original word are
1852 substituted, not patterns that contain any substitution result.
1854 Print the new command line but do not execute it.
1856 Quote the substituted words, preventing further substitutions.
1860 but in addition preserve empty variables as a string containing a NUL.
1861 This is useful to preserve positional arguments for example:
1862 .Bd -literal -offset indent -compact
1863 > set args=('arg 1' '' 'arg 3')
1864 > tcsh -f -c 'echo ${#argv}' $args:gQ
1870 but break into words at blanks, tabs and newlines.
1873 Modifiers are applied to only the first modifiable word (unless
1876 It is an error for no word to be modifiable.
1880 command might have been written as `diff wumpus.man.old
1885 from the first argument on the same line
1888 .Sq echo hello out there
1894 to say it out loud, or
1898 .Sq mail \-s "I forgot my password" rot
1902 correct the spelling of
1905 .Sx Spelling correction
1907 different approach).
1909 There is a special abbreviation for substitutions.
1911 when it is the first character on an input line, is equivalent to
1913 Thus we might have said
1915 to make the spelling correction in the
1917 This is the only history substitution which does not explicitly begin with
1922 as such, only one modifier may be applied to each history
1923 or variable expansion.
1926 more than one may be used, for example
1927 .Bd -literal -offset indent
1928 % mv wumpus.man /usr/man/man1/wumpus.1
1937 A substitution followed by a
1938 colon may need to be insulated from it with braces:
1939 .Bd -literal -offset indent
1940 > mv a.out /usr/games/wumpus
1941 > setenv PATH !$:h:$PATH
1943 > setenv PATH !{\-2$:h}:$PATH
1944 setenv PATH /usr/games:/bin:/usr/bin:.
1947 The first attempt would succeed in
1953 expects another modifier after the second colon
1957 Finally, history can be accessed through the editor as well as through
1958 the substitutions just described.
1963 .Ic history-search-backward
1974 .Ic insert-last-word
1975 editor commands search for
1976 events in the history list and copy them into the input buffer.
1978 .Ic toggle-literal-history
1979 editor command switches between the
1980 expanded and literal forms of history lines in the input buffer.
1984 expand history substitutions
1985 in the current word and in the entire input buffer respectively.
1986 .Ss Alias substitution
1987 The shell maintains a list of aliases which can be set, unset and printed by
1993 After a command line is parsed
1994 into simple commands (see
1996 the first word of each command,
1997 left-to-right, is checked to see if it has an alias.
1998 If so, the first word is
1999 replaced by the alias.
2000 If the alias contains a history reference, it undergoes
2001 .Va History substitution
2002 (q.v.) as though the original command were the
2003 previous input line.
2004 If the alias does not contain a history reference, the
2005 argument list is left untouched.
2007 Thus if the alias for
2014 \-l /usr', the argument list here being undisturbed.
2018 .Sq grep !/etc/passwd
2021 would become `grep bill
2023 Aliases can be used to introduce parser metasyntax.
2027 pr \e!* | lpr'' defines a
2031 (1)s its arguments to the line printer.
2033 Alias substitution is repeated until the first word of the command has no
2035 If an alias substitution does not change the first word (as in the
2036 previous example) it is flagged to prevent a loop.
2037 Other loops are detected and
2040 Some aliases are referred to by the shell; see
2042 .Ss Variable substitution
2043 The shell maintains a list of variables, each of which has as value a list of
2045 The values of shell variables can be displayed and changed with the
2050 The system maintains its own list of
2053 These can be displayed and changed with
2060 (+) Variables may be made read-only with
2063 Read-only variables may not be modified or unset;
2064 attempting to do so will cause an error.
2065 Once made read-only, a variable cannot be made writable,
2068 should be used with caution.
2069 Environment variables cannot be made read-only.
2071 Some variables are set by the shell or referred to by it.
2074 variable is an image of the shell's argument
2075 list, and words of this variable's value are referred to in special ways.
2076 Some of the variables referred to by the shell are toggles;
2077 the shell does not care what their value is, only whether they are set or not.
2080 variable is a toggle which causes command
2083 .Fl v\fR command line option sets this variable.
2084 .Va Special shell variables
2085 lists all variables which are referred to by the shell.
2087 Other operations treat variables numerically.
2090 command permits numeric
2091 calculations to be performed and the result assigned to a variable.
2093 values are, however, always represented as (zero or more) strings.
2095 purposes of numeric operations, the null string is considered to be zero, and
2096 the second and subsequent words of multi-word values are ignored.
2098 After the input line is aliased and parsed, and before each command is
2099 executed, variable substitution is performed keyed by
2103 expansion can be prevented by preceding the
2119 are interpreted later (see
2120 .Sx Command substitution
2123 substitution does not occur there until later,
2127 is passed unchanged if followed by a blank, tab, or
2130 Input/output redirections are recognized before variable expansion, and are
2131 variable expanded separately.
2132 Otherwise, the command name and entire argument
2133 list are expanded together.
2134 It is thus possible for the first (command) word
2135 (to this point) to generate more than one word, the first of which becomes the
2136 command name, and the rest of which become arguments.
2142 modifier the results of variable
2143 substitution may eventually be command and filename substituted.
2147 variable whose value consists of multiple words expands to a (portion of a)
2148 single word, with the words of the variable's value separated by blanks.
2152 modifier is applied to a substitution the variable will expand to
2153 multiple words with each word separated by a blank and quoted to prevent later
2154 command or filename substitution.
2156 The following metasequences are provided for introducing variable values into
2158 Except as noted, it is an error to reference a variable which
2161 .Bl -tag -width XXXXXXXXXX -offset indent -compact
2165 Substitutes the words of the value of variable
2171 from following characters which would
2172 otherwise be part of it.
2173 Shell variables have names consisting of
2174 letters and digits starting with a letter.
2175 The underscore character is
2176 considered a letter.
2179 is not a shell variable, but is set in the
2180 environment, then that value is returned (but some of the other forms
2181 given below are not available in this case).
2182 .It Ar $name[selector]
2183 .It Ar ${name[selector]}
2184 Substitutes only the selected words from the value of
2190 substitution and may consist of
2191 a single number or two numbers separated by a
2193 The first word of a variable's value is numbered
2195 If the first number of a range is omitted it defaults to
2197 If the last member of a range is omitted it defaults to
2204 It is not an error for a range to be empty if the
2205 second argument is omitted or in range.
2207 Substitutes the name of the file from which command input
2209 An error occurs if the name is not known.
2217 which is equivalent to
2223 modifiers described under
2224 .Sx History substitution ,
2227 can be applied to the substitutions above.
2228 More than one may be used.
2230 Braces may be needed to insulate a variable substitution from a literal colon
2232 .Sx History substitution
2233 (q.v.); any modifiers must appear
2236 The following substitutions can not be modified with
2240 .Bl -tag -width XXXXXXXXXX -offset indent -compact
2243 Substitutes the string
2253 if the current input filename is known,
2258 in interactive shells.
2261 Substitutes the number of words in
2269 Substitutes the number of characters in
2275 Substitutes the number of characters in
2283 Substitutes the (decimal) process number of the (parent) shell.
2285 Substitutes the (decimal) process number of the last
2286 background process started by this shell.
2289 Substitutes the command line of the last command executed.
2292 Substitutes a line from the standard input, with no further interpretation
2294 It can be used to read from the keyboard in a shell script.
2297 always quotes $<, as if it were equivalent to
2303 is waiting for a line to be
2304 typed the user may type an interrupt to interrupt the sequence into
2305 which the line is to be substituted, but
2307 does not allow this.
2311 .Va expand-variables
2314 can be used to interactively expand individual variables.
2315 .Ss "Command, filename and directory stack substitution"
2316 The remaining substitutions are applied selectively to the arguments
2317 of builtin commands.
2318 This means that portions of expressions which are not evaluated are
2319 not subjected to these expansions.
2320 For commands which are not internal to the
2321 shell, the command name is substituted separately from the argument list.
2322 This occurs very late, after input-output redirection is performed, andk
2323 in a child of the main shell.
2324 .Ss "Command substitution"
2325 Command substitution is indicated by a command enclosed in
2328 from such a command is broken into separate words at blanks, tabs and newlines,
2329 and null words are discarded.
2330 The output is variable and command substituted
2331 and put in place of the original string.
2333 Command substitutions inside double
2336 retain blanks and tabs; only newlines force new words.
2338 final newline does not force a new word in any case.
2339 It is thus possible for a
2340 command substitution to yield only part of a word, even if the command outputs
2343 By default, the shell since version 6.12 replaces all newline and carriage
2344 return characters in the command by spaces.
2345 If this is switched off by
2348 newlines separate commands as usual.
2349 .Ss "Filename substitution"
2350 If a word contains any of the characters
2359 it is a candidate for filename substitution, also known as
2361 This word is then regarded as a pattern
2362 .Dq ( glob-pattern ) ,
2364 replaced with an alphabetically sorted list of file names which match the
2367 In matching filenames, the character
2369 at the beginning of a filename or
2370 immediately following a
2372 as well as the character
2375 explicitly (unless either
2379 or both are set(+)).
2382 matches any string of characters,
2383 including the null string.
2386 matches any single character.
2389 matches any one of the characters enclosed.
2393 characters separated by
2395 matches any character lexically between the two.
2397 (+) Some glob-patterns can be negated:
2400 matches any single character
2403 characters and/or ranges of characters in the braces.
2405 An entire glob-pattern can also be negated with
2407 .Bd -literal -offset indent
2409 bang crash crunch ouch
2414 Glob-patterns which do not use
2422 (below) are not negated correctly.
2428 Left-to-right order is preserved:
2429 .Sq /usr/source/s1/{oldls,ls}.c
2432 .Sq /usr/source/s1/oldls.c /usr/source/s1/ls.c
2433 The results of matches are
2434 sorted separately at a low level to preserve this order:
2437 .Sq ../memo ../box ../mbox
2440 was not sorted with the results of matching
2442 It is not an error when this construct expands to files which do not exist,
2443 but it is possible to get an error from a command to which the expanded list
2445 This construct may be nested.
2446 As a special case the words
2451 are passed undisturbed.
2455 at the beginning of a filename refers to home directories.
2456 Standing alone, i.e.,
2458 it expands to the invoker's home directory as
2459 reflected in the value of the
2463 name consisting of letters, digits and
2465 characters the shell searches for a
2466 user with that name and substitutes their home directory; thus
2477 is followed by a character other than a letter or
2479 or appears elsewhere
2480 than at the beginning of a word, it is left undisturbed.
2482 .Sq setenv MANPATH /usr/man:/usr/local/man:~/lib/man
2484 therefore, do home directory substitution as one might hope.
2486 It is an error for a glob-pattern containing
2495 not to match any files.
2496 However, only one pattern in a list of
2497 glob-patterns must match a file (so that, e.g.,
2500 only if there were no files in the current directory ending in
2507 shell variable is set a pattern (or list
2508 of patterns) which matches nothing is left unchanged rather than causing
2513 shell variable can be set to allow
2518 a file glob pattern that matches any string of characters including
2520 recursively traversing any existing sub-directories.
2523 will list all the .c files in the current directory tree.
2524 If used by itself, it will match zero or more sub-directories
2526 .Sq ls /usr/include/**/time.h
2527 will list any file named
2529 in the /usr/include directory tree;
2530 .Sq ls /usr/include/**time.h
2532 any file in the /usr/include directory tree ending in
2535 .Sq ls /usr/include/**time**.h
2536 will match any .h file with
2539 in a subdirectory name or in the filename itself).
2540 To prevent problems with recursion, the
2542 glob-pattern will not
2543 descend into a symbolic link containing a directory.
2551 shell variable can be set to prevent filename substitution,
2554 editor command, normally bound to
2557 used to interactively expand individual filename substitutions.
2558 .Ss "Directory stack substitution (+)"
2559 The directory stack is a list of directories, numbered from zero, used by the
2564 builtin commands (q.v.).
2566 can print, store in a file, restore and clear the directory stack
2567 at any time, and the
2571 shell variables can be set to
2572 store the directory stack automatically on logout and restore it on login.
2575 shell variable can be examined to see the directory stack and
2576 set to put arbitrary directories into the directory stack.
2580 followed by one or more digits expands to an entry in
2581 the directory stack.
2584 expands to the last directory in
2587 .Bd -literal -offset indent
2604 shell variables and the
2606 editor command apply to directory stack as well as filename substitutions.
2607 .Ss "Other substitutions (+)"
2608 There are several more transformations involving filenames, not strictly
2609 related to the above but mentioned here for completeness.
2611 filename may be expanded to a full path when the
2613 variable (q.v.) is set to
2615 Quoting prevents this expansion, and
2618 editor command does it on demand.
2620 .Va normalize-command
2621 editor command expands commands in PATH into
2622 full paths on demand.
2629 as the old working directory
2630 (equivalent to the shell variable
2632 This is not a substitution at all, but an abbreviation recognized by only
2634 Nonetheless, it too can be prevented by quoting.
2636 The next three sections describe how the shell executes commands and
2637 deals with their input and output.
2638 .Ss "Simple commands, pipelines and sequences"
2639 A simple command is a sequence of words, the first of which specifies the
2640 command to be executed.
2641 A series of simple commands joined by
2645 The output of each command in a pipeline is connected to the
2648 Simple commands and pipelines may be joined into sequences with
2651 be executed sequentially.
2652 Commands and pipelines can also be joined into
2657 indicating, as in the C language, that the second
2658 is to be executed only if the first fails or succeeds respectively.
2660 A simple command, pipeline or sequence may be placed in parentheses,
2662 to form a simple command, which may in turn be a component of a pipeline or
2664 A command, pipeline or sequence can be executed
2665 without waiting for it to terminate by following it with an
2667 .Ss "Builtin and non-builtin command execution"
2668 Builtin commands are executed within the shell.
2669 If any component of a
2670 pipeline except the last is a builtin command, the pipeline is executed
2673 Parenthesized commands are always executed in a subshell.
2674 .Bd -literal -offset indent
2680 directory, leaving you where you were
2681 (printing this after the home directory), while
2682 .Bd -literal -offset indent
2689 Parenthesized commands are most often
2692 from affecting the current shell.
2694 When a command to be executed is found not to be a builtin command the shell
2695 attempts to execute the command via
2697 Each word in the variable
2699 names a directory in which the shell will look for the
2701 If the shell is not given a
2704 hashes the names in these directories into an internal table so that it will
2707 in only a directory where there is a possibility that the
2708 command resides there.
2709 This greatly speeds command location when a large
2710 number of directories are present in the search path. This hashing mechanism is
2713 .Bl -enum -width indent
2715 If hashing is turned explicitly off via
2718 If the shell was given a
2721 For each directory component of
2723 which does not begin with a
2726 If the command contains a
2730 In the above four cases the shell concatenates each component of the path
2731 vector with the given command name to form a path name of a file which it
2732 then attempts to execute it. If execution is successful, the search stops.
2734 If the file has execute permissions but is not an executable to the system
2735 (i.e., it is neither an executable binary nor a script that specifies its
2736 interpreter), then it is assumed to be a file containing shell commands and
2737 a new shell is spawned to read it.
2740 special alias may be set
2741 to specify an interpreter other than the shell itself.
2743 On systems which do not understand the
2745 script interpreter convention
2746 the shell may be compiled to emulate it; see the
2750 If so, the shell checks the first line of the file to
2751 see if it is of the form
2752 .Sq #!interpreter arg ...
2759 file to it on standard input.
2761 The standard input and standard output of a command may be redirected with the
2764 .Bl -tag -width XXXXXXXXX -offset indent -compact
2768 (which is first variable, command and filename
2769 expanded) as the standard input.
2771 Read the shell input up to a line which is identical to
2774 is not subjected to variable, filename or command substitution, and each input
2777 before any substitutions are done on this input
2789 command substitution is performed on the intervening lines, allowing
2797 Commands which are substituted have all blanks, tabs,
2798 and newlines preserved, except for the final newline which is dropped.
2800 resultant text is placed in an anonymous temporary file which is given to the
2801 command as standard input.
2809 is used as standard output.
2810 If the file does not exist
2811 then it is created; if the file exists, it is truncated, its previous contents
2814 If the shell variable
2816 is set, then the file must not exist or be a
2817 character special file (e.g., a terminal or
2819 or an error results.
2820 This helps prevent accidental destruction of files.
2824 can be used to suppress this check.
2830 is allowed on empty files;
2833 is set, an interacive confirmation is presented, rather than an
2838 route the diagnostic output into the specified file as
2839 well as the standard output.
2841 is expanded in the same way as
2843 input filenames are.
2851 , but appends output to the end of
2853 If the shell variable
2855 is set, then it is an error for
2858 to exist, unless one of the
2863 A command receives the environment in which the shell was invoked as modified
2864 by the input-output parameters and the presence of the command in a pipeline.
2865 Thus, unlike some previous shells, commands run from a file of shell commands
2866 have no access to the text of the commands by default; rather they receive the
2867 original standard input of the shell.
2870 mechanism should be used to
2871 present inline data.
2872 This permits shell command scripts to function as
2873 components of pipelines and allows the shell to block read its input.
2875 that the default standard input for a command run detached is
2879 but the original standard input of the shell.
2880 If this is a terminal and if the process attempts to read from the terminal,
2881 then the process will block and the user will be notified (see
2884 Diagnostic output may be directed through a pipe with the standard output.
2890 The shell cannot presently redirect diagnostic output without also redirecting
2891 standard output, but
2892 .Sq \&( command > output-file ) >& error-file
2893 is often an acceptable workaround.
2900 to send output to the terminal.
2902 Having described how the shell accepts, parses and executes
2903 command lines, we now turn to a variety of its useful features.
2905 The shell contains a number of commands which can be used to regulate the
2906 flow of control in command files (shell scripts) and (in limited but
2907 useful ways) from terminal input.
2908 These commands all operate by forcing the
2909 shell to reread or skip in its input and, due to the implementation,
2910 restrict the placement of some of the commands.
2917 statements, as well as the
2921 statement, require that the major
2922 keywords appear in a single simple command on an input line as shown below.
2924 If the shell's input is not seekable, the shell buffers up input whenever
2925 a loop is being read and performs seeks in this internal buffer to
2926 accomplish the rereading implied by the loop.
2927 (To the extent that this allows, backward
2929 s will succeed on non-seekable inputs.)
2937 use expressions with a common syntax.
2938 The expressions can include any
2939 of the operators described in the next three sections.
2942 builtin command (q.v.) has its own separate syntax.
2943 .Ss "Logical, arithmetical and comparison operators"
2944 These operators are similar to those of C and have the same precedence.
2947 .Bl -tag -width XXXXXX -offset indent -compact
2948 .It || && | & == != =~ !~ <= >=
2949 .It < > << >> + \- * / % ! ~ ( )
2952 Here the precedence increases to the right,
2973 groups, at the same level.
2981 their arguments as strings; all others operate on numbers.
2990 except that the right hand side is a
2992 .Sx Filename substitution )
2993 against which the left hand operand is matched.
2994 This reduces the need for use of the
2996 builtin command in shell scripts when all that is really needed is
3000 missing arguments are considered
3002 The results of all expressions are
3003 strings, which represent decimal numbers.
3004 It is important to note that
3005 no two components of an expression can appear in the same word; except
3006 when adjacent to components of expressions which are syntactically
3007 significant to the parser
3015 surrounded by spaces.
3016 .Ss "Command exit status"
3017 Commands can be executed in expressions and their exit status
3018 returned by enclosing them in braces
3020 Remember that the braces should
3021 be separated from the words of the command by spaces.
3023 succeed, returning true, i.e.,
3025 if the command exits with status 0,
3026 otherwise they fail, returning false, i.e.,
3028 If more detailed status
3029 information is required then the command should be executed outside of an
3032 shell variable examined.
3033 .Ss "File inquiry operators"
3034 Some of these operators perform true/false tests on files and related
3036 They are of the form
3042 .Bl -tag -width XXX -offset indent -compact
3050 Executable in the path or shell builtin, e.g.,
3073 Block special file (+)
3075 Character special file (+)
3077 Named pipe (fifo) (+) *
3079 Socket special file (+) *
3081 Set-user-ID bit is set (+)
3083 Set-group-ID bit is set (+)
3085 Sticky bit is set (+)
3087 (which must be a digit) is an open file descriptor
3088 for a terminal device (+)
3090 Has been migrated (Convex only) (+)
3092 Applies subsequent operators in a multiple-operator test to a symbolic link
3093 rather than to the file to which the link points (+) *
3097 is command and filename expanded and then tested to
3098 see if it has the specified relationship to the real user.
3101 does not exist or is inaccessible or, for the operators indicated by
3103 if the specified file type does not exist on the current system,
3104 then all inquiries return false, i.e.,
3107 These operators may be combined for conciseness:
3112 .Sq \&-x file && \&-y file .
3118 for plain executable files, but not for directories.
3121 may be used in a multiple-operator test to apply subsequent operators
3122 to a symbolic link rather than to the file to which the link points.
3125 is true for links owned by the invoking user.
3130 are always true for links and false for
3133 has a different meaning when it is the last operator
3134 in a multiple-operator test; see below.
3136 It is possible but not useful, and sometimes misleading, to combine operators
3139 to be a file with operators which do not
3146 with a non-file operator
3147 can lead to particularly strange results.
3149 Other operators return other information, i.e., not just
3154 They have the same format as before;
3158 .Bl -tag -width XXX -offset indent -compact
3160 Last file access time, as the number of seconds since the epoch
3164 , but in timestamp format, e.g.,
3165 .Sq Fri May 14 16:36:10 1993
3167 Last file modification time
3171 , but in timestamp format
3173 Last inode modification time
3177 , but in timestamp format
3185 ile identifier, in the form
3189 The name of the file pointed to by a symbolic link
3191 Number of (hard) links
3193 Permissions, in octal, without leading zero
3210 is writable by group and other,
3224 Username, or the numeric userid if the username is unknown
3228 Groupname, or the numeric groupid if the groupname is unknown
3233 Only one of these operators may appear in a multiple-operator test, and it
3237 has a different meaning at the end of and
3238 elsewhere in a multiple-operator test.
3241 is a valid return value
3242 for many of these operators, they do not return
3244 when they fail: most
3252 If the shell is compiled with POSIX defined (see the
3255 variable), the result of a file inquiry is based on the permission bits of
3256 the file and not on the result of the
3259 For example, if one tests a file with
3260 .Fl w\fR whose permissions would
3261 ordinarily allow writing but which is on a file system mounted read-only,
3262 the test will succeed in a POSIX shell but fail in a non-POSIX shell.
3264 File inquiry operators can also be evaluated with the
3269 The shell associates a
3273 current jobs, printed by the
3275 command, and assigns them small integer
3277 When a job is started asynchronously with
3279 , the shell prints a
3280 line which looks like
3284 indicating that the job which was started asynchronously was job number 1 and
3285 had one (top-level) process, whose process id was 1234.
3287 If you are running a job and wish to do something else you may hit the suspend
3290 which sends a STOP signal to the current job.
3291 The shell will then normally
3292 indicate that the job has been
3294 and print another prompt.
3297 shell variable is set, all jobs will be listed
3300 builtin command; if it is set to
3303 be in long format, like
3305 You can then manipulate the state of the suspended job.
3306 You can put it in the
3310 command or run some other commands and
3311 eventually bring the job back into the
3320 takes effect immediately and is like an interrupt
3321 in that pending output and unread input are discarded when it is typed.
3324 builtin command causes the shell to wait for all background
3329 key sends a delayed suspend signal, which does not generate a STOP
3330 signal until a program attempts to
3332 (2) it, to the current job.
3333 This can usefully be typed ahead when you have prepared some commands for a
3334 job which you wish to stop after it has read them.
3337 key performs this function in
3342 `^Y' is an editing command.
3345 A job being run in the background stops if it tries to read from the
3347 Background jobs are normally allowed to produce output, but this can
3348 be disabled by giving the command
3350 If you set this tty option,
3351 then background jobs will stop when they try to produce output like they do
3352 when they try to read input.
3354 There are several ways to refer to jobs in the shell.
3357 introduces a job name.
3358 If you wish to refer to job number 1, you can name it
3361 Just naming a job brings it to the foreground; thus
3366 , bringing job 1 back into the foreground.
3369 resumes job 1 in the background, just like
3371 A job can also be named
3372 by an unambiguous prefix of the string typed in to start it:
3375 normally restart a suspended
3377 job, if there were only one suspended
3378 job whose name began with the string
3380 It is also possible to say
3382 to specify a job whose text contains
3384 if there is only one such job.
3386 The shell maintains a notion of the current and previous jobs.
3388 pertaining to jobs, the current job is marked with a
3390 and the previous job
3397 , and (by analogy with the syntax of
3402 all refer to the current job, and
3405 to the previous job.
3407 The job control mechanism requires that the
3413 It is an artifact from a
3415 implementation of the tty
3416 driver which allows generation of interrupt characters from the keyboard to
3423 details on setting options in the new tty driver.
3424 .Ss "Status reporting"
3425 The shell learns immediately whenever a process changes state.
3427 informs you whenever a job becomes blocked so that no further progress is
3428 possible, but only right before it prints a prompt.
3429 This is done so that it
3430 does not otherwise disturb your work.
3431 If, however, you set the shell variable
3433 , the shell will notify you immediately of changes of status in
3435 There is also a shell command
3438 single process so that its status changes will be immediately reported.
3442 marks the current process; simply say
3445 starting a background job to mark it.
3447 When you try to leave the shell while jobs are stopped, you will be
3449 .Sq There are suspended jobs.
3454 If you do this or immediately try to exit again, the shell
3455 will not warn you a second time, and the suspended jobs will be terminated.
3456 .Ss "Automatic, periodic and timed events (+)"
3457 There are various ways to run commands and take other actions automatically
3458 at various times in the
3461 They are summarized here,
3462 and described in detail under the appropriate
3463 .Va Builtin commands
3465 .Va Special shell variables
3471 builtin command puts commands in a scheduled-event list,
3472 to be executed by the shell at a given time.
3488 can be set, respectively, to execute commands when the shell wants
3489 to ring the bell, when the working directory changes, every
3491 minutes, before each prompt, before each command gets executed, after each
3492 command gets executed, and when a job is started or is brought into the
3497 shell variable can be set to log out or lock the shell
3498 after a given number of minutes of inactivity.
3502 shell variable can be set to check for new mail periodically.
3506 shell variable can be set to print the exit status
3507 of commands which exit with a status other than zero.
3511 shell variable can be set to ask the user, when
3514 typed, if that is really what was meant.
3518 shell variable can be set to execute the
3521 command after the completion of any process that takes more than a given
3522 number of CPU seconds.
3528 shell variables can be set to report when
3529 selected users log in or out, and the
3531 builtin command reports
3532 on those users at any time.
3533 .Ss "Native Language System support (+)"
3534 The shell is eight bit clean
3535 (if so compiled; see the
3538 and thus supports character sets needing this capability.
3539 NLS support differs depending on whether or not
3540 the shell was compiled to use the system's NLS (again, see
3543 In either case, 7-bit ASCII is the default character code
3544 (e.g., the classification of which characters are printable) and sorting,
3549 environment variables
3550 causes a check for possible changes in these respects.
3552 When using the system's NLS, the
3554 (3) function is called
3555 to determine appropriate character code/classification and sorting
3556 (e.g., a 'en_CA.UTF-8' would yield "UTF-8" as a character code).
3557 This function typically examines the
3561 environment variables; refer to the system documentation for further details.
3562 When not using the system's NLS, the shell simulates it by assuming that the
3563 ISO 8859-1 character set is used
3564 whenever either of the
3568 variables are set, regardless of
3570 Sorting is not affected for the simulated NLS.
3572 In addition, with both real and simulated NLS, all printable
3573 characters in the range \e200\-\e377, i.e., those that have
3576 bindings, are automatically rebound to
3577 .Va self-insert-command
3578 The corresponding binding for the escape-
3580 sequence, if any, is
3582 These characters are not rebound if the
3584 environment variable
3586 This may be useful for the simulated NLS or a primitive real NLS
3587 which assumes full ISO 8859-1.
3591 range \e240\-\e377 are effectively undone.
3592 Explicitly rebinding the relevant keys with
3594 is of course still possible.
3596 Unknown characters (i.e., those that are neither printable nor control
3597 characters) are printed in the format \ennn.
3598 If the tty is not in 8 bit mode, other 8 bit characters are printed by
3599 converting them to ASCII and using standout mode.
3601 never changes the 7/8 bit mode of the tty and tracks user-initiated
3602 changes of 7/8 bit mode.
3603 NLS users (or, for that matter, those who want to
3604 use a meta key) may need to explicitly set
3605 the tty in 8 bit mode through the appropriate
3608 command in, e.g., the
3611 .Ss "OS variant support (+)"
3612 A number of new builtin commands are provided to support features in
3613 particular operating systems.
3614 All are described in detail in the
3615 .Va Builtin commands
3618 On systems that support TCF (aix-ibm370, aix-ps2),
3622 get and set the system execution path,
3626 get and set the experimental version prefix
3629 migrates processes between sites.
3633 prints the site on which each job is executing.
3637 executes commands of the underlying BS2000/OSD
3642 adds shared libraries to the current environment,
3644 changes the rootnode and
3646 changes the systype.
3650 is equivalent to Mach's
3654 Under Masscomp/RTU and Harris CX/UX,
3662 runs a command under the specified
3667 prints or sets the universe.
3675 environment variables
3676 indicate respectively the vendor, operating system and machine type
3677 (microprocessor class or machine model) of the
3678 system on which the shell thinks it is running.
3679 These are particularly useful when sharing one's home directory between several
3680 types of machines; one can, for example,
3682 set path = (~/bin.$MACHTYPE /usr/ucb /bin /usr/bin .)
3686 and put executables compiled for each machine in the
3687 appropriate directory.
3692 variable indicates what options were chosen when the shell was compiled.
3700 shell variables and the system-dependent locations of
3701 the shell's input files (see
3704 .Ss "Signal handling"
3705 Login shells ignore interrupts when reading the file
3707 The shell ignores quit signals unless started with
3709 Login shells catch the terminate signal, but non-login shells inherit the
3710 terminate behavior from their parents.
3711 Other signals have the values which the shell inherited from its parent.
3713 In shell scripts, the shell's handling of interrupt and terminate signals
3714 can be controlled with
3716 , and its handling of hangups can be
3722 The shell exits on a hangup (see also the
3726 default, the shell's children do too, but the shell does not send them a
3727 hangup when it exits.
3729 arranges for the shell to send a hangup to
3730 a child when it exits, and
3732 sets a child to ignore hangups.
3733 .Ss "Terminal management (+)"
3734 The shell uses three different sets of terminal (
3737 `edit', used when editing,
3739 , used when quoting literal characters,
3742 , used when executing commands.
3743 The shell holds some settings in each mode constant, so commands which leave
3744 the tty in a confused state do not interfere with the shell.
3745 The shell also matches changes in the speed and padding of the tty.
3746 The list of tty modes that are kept constant
3747 can be examined and modified with the
3750 Note that although the editor uses CBREAK mode (or its equivalent),
3751 it takes typed-ahead characters anyway.
3759 commands can be used to
3760 manipulate and debug terminal capabilities from the command line.
3762 On systems that support SIGWINCH or SIGWINDOW, the shell
3763 adapts to window resizing automatically and adjusts the environment
3772 contains li# and co# fields, the shell adjusts
3773 them to reflect the new window size.
3775 The next sections of this manual describe all of the available
3776 .Va Builtin commands
3780 .Va Special shell variables
3781 .Ss "Builtin commands"
3782 .Bl -tag -width XXXXXXX -offset indent
3792 Does nothing, successfully.
3795 .It Ar @ name = expr
3796 .It Ar @ name[index] = expr
3798 .It Ar @name[index]++|--
3799 The first form prints the values of all shell variables.
3801 The second form assigns the value of
3805 The third form assigns the value of
3820 may contain the operators
3835 then at least that part of
3837 must be placed within
3839 Note that the syntax of
3841 has nothing to do with that described
3845 The fourth and fifth forms increment (
3870 must be separated by spaces.
3871 .It Ar alias [name [wordlist]]
3872 Without arguments, prints all aliases.
3875 , prints the alias for name.
3885 is command and filename substituted.
3895 Shows the amount of dynamic memory acquired, broken down into used and free
3897 With an argument shows the number of free and used blocks in each size
3899 The categories start at size 8 and double at each step.
3900 This command's output may vary across system types, because systems other
3901 than the VAX may use a different memory allocator.
3903 Puts the specified jobs (or, without arguments, the current job)
3904 into the background, continuing each if it is stopped.
3906 may be a number, a string,
3915 .It Ar bindkey Oo Fl l Ns | Ns Fl d Ns | Ns Fl e Ns | Ns Fl v Ns | Ns Fl u Oc (+)
3916 .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 (+)
3917 .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 (+)
3918 .\" .It Ar macro can't take too many words, so I used \fB in the previous tags
3919 Without options, the first form lists all bound keys and the editor command to which each is bound,
3920 the second form lists the editor command to which
3923 the third form binds the editor command
3929 .Bl -tag -width XXX -compact
3931 Lists all editor commands and a short description of each.
3933 Binds all keys to the standard bindings for the default editor,
3942 (1)\-style bindings.
3948 (1)\-style bindings.
3952 Lists or changes key-bindings in the alternative key map.
3953 This is the key map used in
3959 a control character written ^
3969 a meta character written M-
3974 a function key written F-
3979 or an extended prefix key written X-
3986 is interpreted as a symbolic arrow key name, which may be one of
4004 .Va self-insert-command
4010 is interpreted as a builtin or external command instead of an
4014 is taken as a literal string and treated as terminal input
4021 reinterpreted, and this continues for ten levels of interpretation.
4023 Forces a break from option processing, so the next word is taken as
4025 even if it begins with '\&-'.
4027 (or any invalid option)
4028 Prints a usage message.
4032 may be a single character or a string.
4033 If a command is bound to a string, the first character of the string is bound to
4034 .Va sequence-lead-in
4035 and the entire string is bound to the command.
4037 Control characters in
4039 can be literal (they can be typed by preceding
4040 them with the editor command
4045 written caret-character style, e.g.,
4049 (caret-question mark).
4053 can contain backslashed
4054 escape sequences (in the style of System V
4058 .Bl -tag -width XXXX -compact -offset indent
4076 The ASCII character corresponding to the octal number
4080 `\e' nullifies the special meaning of the following character, if it has
4085 .It bs2cmd Va bs2000-command
4089 to the BS2000 command interpreter for
4090 execution. Only non-interactive commands can be executed, and it is
4091 not possible to execute any command that would overlay the image
4092 of the current process, like /EXECUTE or /CALL-PROCEDURE. (BS2000 only)
4094 Causes execution to resume after the
4101 The remaining commands on the
4102 current line are executed.
4103 Multi-level breaks are thus
4104 possible by writing them all on one line.
4106 Causes a break from a
4108 , resuming after the
4112 Prints the names of all builtin commands.
4118 Available only if the shell was so compiled;
4123 .It case \fIlabel\fB:
4126 statement as discussed below.
4132 .Fl v\fR] [\I--\fR] [
4137 is given, changes the shell's working directory
4144 variable is not set, in which case a
4151 it is interpreted as the previous working directory
4153 .Va Other substitutions
4158 is not a subdirectory of the current directory
4159 (and does not begin with
4165 ), each component of the variable
4167 is checked to see if it has a subdirectory
4172 is a shell variable whose value
4175 or '.', then this is tried to see if it is a directory, and
4177 .Fl p\fR option is implied.
4181 .Fl p\fR, prints the final directory stack, just like
4186 .Fl v\fR flags have the same effect on
4194 .Fl \-\fR forces a break from option processing so the next word
4195 is taken as the directory
4197 even if it begins with '\-'. (+)
4213 [\fIword\fB/\fIpattern\fB/
4224 Without arguments, lists all completions.
4227 , lists completions for
4233 etc., defines completions.
4237 may be a full command name or a glob-pattern
4239 .Va Filename substitution
4244 completion should be used only when
4249 specifies which word relative to the current word
4250 is to be completed, and may be one of the following:
4256 Current-word completion.
4258 is a glob-pattern which must match the beginning of the current word on
4261 is ignored when completing the current word.
4268 when completing the current word.
4271 Next-word completion.
4273 is a glob-pattern which must match the beginning of the previous word on
4279 , but must match the beginning of the word two before the current word.
4282 Position-dependent completion.
4284 is a numeric range, with the same syntax used to index shell
4285 variables, which must include the current word.
4290 , the list of possible completions, may be one of the following:
4296 Bindings (editor commands)
4298 Commands (builtin or external commands)
4300 External commands which begin with the supplied path prefix
4304 Directories which begin with the supplied path prefix
4306 Environment variables
4310 Filenames which begin with the supplied path prefix
4330 files which begin with the supplied path prefix
4347 Words from the variable
4350 Words from the given list
4352 Words from the output of command
4356 is an optional glob-pattern.
4357 If given, words from only
4364 shell variable is ignored.
4365 The last three types of completion may not have a
4371 as an explanatory message when
4374 editor command is used.
4377 is a single character to be appended to a successful
4379 If null, no character is appended.
4380 If omitted (in which
4381 case the fourth delimiter can also be omitted), a slash is appended to
4382 directories and a space to other words.
4385 invoked from \`...\` version has additional environment
4386 variable set, the variable name is \%
4389 contains (as its name indicates) contents of the current (already
4390 typed in) command line. One can examine and use contents of the
4393 \% variable in her custom script to build more
4394 sophisticated completions (see completion for svn(1) included in
4397 Now for some examples.
4398 Some commands take only directories as arguments,
4399 so there's no point completing plain files.
4401 > complete cd 'p/1/d/'
4403 completes only the first word following
4405 (`p/1') with a directory.
4407 -type completion can also be used to narrow down command completion:
4413 > complete \-co* 'p/0/(compress)/'
4419 This completion completes commands (words in position 0,
4432 indicates that this completion is to be used with only
4435 > complete find 'n/\-user/u/'
4443 immediately following
4445 is completed from the list of users.
4447 > complete cc 'c/\-I/d/'
4457 is completed as a directory.
4458 `\-I' is not taken as part of the
4459 directory because we used lowercase
4464 s are useful with different commands.
4466 > complete alias 'p/1/a/'
4468 > complete man 'p/*/c/'
4470 > complete set 'p/1/s/'
4472 > complete true 'p/1/x:Truth has no options./'
4474 These complete words following
4481 with shell variables.
4482 `true' doesn't have any options, so
4484 does nothing when completion
4485 is attempted and prints
4486 .Sq Truth has no options.
4487 when completion choices are listed.
4491 example, and several other examples below, could
4492 just as well have used 'c/*' or 'n/*' as 'p/*'.
4494 Words can be completed from a variable evaluated at completion time,
4496 > complete ftp 'p/1/$hostnames/'
4498 > set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu)
4502 rtfm.mit.edu tesla.ee.cornell.edu
4506 > set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net)
4510 rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net
4512 or from a command run at completion time:
4514 > complete kill 'p/*/\`ps | awk \e{print\e \e$1\e}\`/'
4518 23113 23377 23380 23406 23429 23529 23530 PID
4522 command does not itself quote its arguments,
4523 so the braces, space and
4527 must be quoted explicitly.
4529 One command can have multiple completions:
4531 > complete dbx 'p/2/(core)/' 'p/*/c/'
4533 completes the second argument to
4538 arguments with commands.
4539 Note that the positional completion is specified
4540 before the next-word completion.
4541 Because completions are evaluated from left to right, if
4542 the next-word completion were specified first it would always match
4543 and the positional completion would never be executed.
4545 common mistake when defining a completion.
4549 pattern is useful when a command takes files with only
4550 particular forms as arguments.
4553 > complete cc 'p/*/f:*.[cao]/'
4557 arguments to files ending in only
4564 can also exclude files, using negation of a glob-pattern as
4566 .Va Filename substitution
4569 > complete rm 'p/*/f:^*.{c,h,cc,C,tex,1,man,l,y}/'
4571 to exclude precious source code from
4575 could still type excluded names manually or override the completion
4577 .Va complete-word-raw
4579 .Va list-choices-raw
4580 editor commands (q.v.).
4600 respectively, but they use the
4602 argument in a different way: to
4603 restrict completion to files beginning with a particular path prefix.
4605 example, the Elm mail program uses
4607 as an abbreviation for one's mail
4611 > complete elm c@=@F:$HOME/Mail/@
4621 to avoid confusion with the
4623 argument, and we used
4626 because home directory substitution works at only the
4627 beginning of a word.
4630 is used to add a nonstandard suffix
4633 for directories) to completed words.
4635 > complete finger 'c/*@/$hostnames/' 'p/1/u/@'
4637 completes arguments to
4639 from the list of users, appends an
4642 and then completes after the
4648 again the order in which the completions are specified.
4650 Finally, here's a complex example for inspiration:
4654 \&'n/\-name/f/' 'n/\-newer/f/' 'n/\-{,n}cpio/f/' \e
4656 \&\'n/\-exec/c/' 'n/\-ok/c/' 'n/\-user/u/' \e
4658 \&'n/\-group/g/' 'n/\-fstype/(nfs 4.2)/' \e
4660 \&'n/\-type/(b c d f l p s)/' \e
4662 \'c/\-/(name newer cpio ncpio exec ok user \e
4664 group fstype type atime ctime depth inum \e
4666 ls mtime nogroup nouser perm print prune \e
4672 This completes words following
4680 (note the pattern which matches both) to files,
4685 to commands, words following
4689 to users and groups respectively
4696 It also completes the switches themselves from the given list
4700 and completes anything not otherwise completed to a directory.
4703 Remember that programmed completions are ignored if the word being completed
4704 is a tilde substitution (beginning with
4706 ) or a variable (beginning with
4715 Continues execution of the nearest enclosing
4719 The rest of the commands on the current line are executed.
4722 Labels the default case in a
4725 It should come after all
4741 The first form prints the directory stack.
4742 The top of the stack is at the
4743 left and the first directory in the stack is the current directory.
4749 in the output is expanded explicitly
4752 or the pathname of the home directory for user \fIname\fP.
4755 .Fl n\fR, entries are wrapped before they reach the edge of the screen.
4758 .Fl v\fR, entries are printed one per line, preceded by their stack positions.
4763 .Fl v\fR takes precedence.
4764 .Fl p\fR is accepted but does nothing.
4769 .Fl S\fR, the second form saves the directory stack to
4777 .Fl L\fR, the shell sources
4779 , which is presumably
4780 a directory stack file saved by the
4781 .Fl S\fR option or the
4794 Note that login shells do the equivalent of
4804 is normally sourced before
4813 The last form clears the directory stack.
4822 to the shell's standard
4823 output, separated by spaces and terminated with a newline.
4826 shell variable may be set to emulate (or not) the flags and escape
4827 sequences of the BSD and/or System V versions of
4837 Exercises the terminal capabilities (see
4841 For example, 'echotc home' sends the cursor to the home position,
4842 \&'echotc cm 3 10' sends it to column 3 and row 10, and
4843 \&'echotc ts 0; echo "This is a test."; echotc fs' prints "This is a test."
4849 is 'baud', 'cols', 'lines', 'meta' or 'tabs', prints the
4850 value of that capability ("yes" or "no" indicating that the terminal does
4851 or does not have that capability).
4852 One might use this to make the output
4853 from a shell script less verbose on slow terminals, or limit command
4854 output to the number of lines on the screen:
4856 > set history=\`echotc lines\`
4860 Termcap strings may contain wildcards which will not echo correctly.
4861 One should use double quotes when setting a shell variable to a terminal
4862 capability string, as in the following example that places the date in
4865 > set tosl="\`echotc ts 0\`"
4867 > set frsl="\`echotc fs\`"
4869 > echo \-n "$tosl";date; echo \-n "$frsl"
4872 .Fl s\fR, nonexistent capabilities return the empty string rather
4873 than causing an error.
4875 .Fl v\fR, messages are verbose.
4886 See the description of the
4900 Treats the arguments as input to the
4901 shell and executes the resulting command(s) in the context
4902 of the current shell.
4903 This is usually used to execute commands
4904 generated as the result of command or variable substitution,
4905 because parsing occurs before these substitutions.
4908 (1) for a sample use of
4913 Executes the specified command in place of the current shell.
4918 The shell exits either with the value of the specified
4920 (an expression, as described under
4930 Brings the specified jobs (or, without arguments, the current job)
4931 into the foreground, continuing each if it is stopped.
4933 may be a number, a string,
4953 (which is a file inquiry operator as described under
4954 .Va File inquiry operators
4957 and returns the results as a
4958 space-separated list.
4960 .B foreach \fIname \fB(\fIwordlist\fB)
4966 Successively sets the variable
4970 and executes the sequence of commands between this command
4977 must appear alone on separate lines.) The builtin command
4979 may be used to continue the loop prematurely and
4982 to terminate it prematurely.
4983 When this command is read from the terminal, the loop is read once
4988 ) before any statements in
4989 the loop are executed.
4990 If you make a mistake typing in a
4991 loop at the terminal you can rub it out.
4995 Prints the system execution path.
4999 Prints the experimental version prefix.
5007 parameter is not recognized and words are
5008 delimited by null characters in the output.
5010 programs which wish to use the shell to filename expand a list of words.
5014 is filename and command-substituted to
5015 yield a string of the form
5017 The shell rewinds its
5018 input as much as possible, searches for a line of the
5021 , possibly preceded by blanks or tabs, and
5022 continues execution after that line.
5025 Prints a statistics line indicating how effective the
5026 internal hash table has been at locating commands (and avoiding
5031 is attempted for each component of the
5033 where the hash function indicates a possible hit, and
5034 in each component which does not begin with a
5039 (2), prints only the number and size of
5054 .B history \-c \fR(+)
5055 The first form prints the history event list.
5060 most recent events are printed or saved.
5062 .Fl h\fR, the history list is printed without leading numbers.
5065 is specified, timestamps are printed also in comment form.
5066 (This can be used to
5067 produce files suitable for loading with 'history \-L' or 'source \-h'.)
5069 .Fl r\fR, the order of printing is most recent
5070 first rather than oldest first.
5075 .Fl S\fR, the second form saves the history list to
5077 If the first word of the
5079 shell variable is set to a
5080 number, at most that many lines are saved.
5081 If the second word of
5085 , the history list is merged with the
5086 existing history file instead of replacing it (if there is one) and
5087 sorted by time stamp.
5088 (+) Merging is intended for an environment like
5090 with several shells in simultaneous use.
5091 If the second word of
5095 and the third word is set to
5097 , the history file update
5098 will be serialized with other shell sessions that would possibly like
5099 to merge history at exactly the same time.
5102 .Fl L\fR, the shell appends
5104 , which is presumably a
5105 history list saved by the
5106 .Fl S\fR option or the
5109 to the history list.
5111 .Fl L\fR, but the contents of
5114 into the history list and sorted by timestamp.
5124 `history \-L' is exactly like 'source \-h' except that it does not require a
5127 Note that login shells do the equivalent of
5137 is normally sourced before
5148 is set, the first and second forms print and save the literal
5149 (unexpanded) form of the history list.
5151 The last form clears the history list.
5161 such that it will exit on a hangup
5162 signal and arranges for the shell to send it a hangup signal when the shell
5164 Note that commands may set their own response to hangups, overriding
5166 Without an argument, causes the non-interactive shell only to
5167 exit on a hangup for the remainder of the script.
5174 .B if (\fIexpr\fB) \fIcommand
5177 (an expression, as described under
5180 evaluates true, then
5183 Variable substitution on
5185 happens early, at the same time it
5186 does for the rest of the
5190 must be a simple command, not an alias, a pipeline, a command list
5191 or a parenthesized command list, but it may have arguments.
5192 Input/output redirection occurs even if
5199 executed; this is a bug.
5201 .B if (\fIexpr\fB) then
5205 .B else if (\fIexpr2\fB) then
5217 is true then the commands to the
5220 are executed; otherwise if
5223 the commands to the second
5229 pairs are possible; only one
5235 part is likewise optional.
5240 must appear at the beginning of input lines;
5243 must appear alone on its input line or after an
5253 to the current environment.
5255 to remove a shared library.
5260 Lists the active jobs.
5262 .Fl l\fR, lists process
5263 IDs in addition to the normal information.
5264 On TCF systems, prints
5265 the site on which each job is executing.
5280 The first and second forms sends the specified
5283 is given, the TERM (terminate) signal) to the specified jobs or processes.
5285 may be a number, a string,
5296 Signals are either given by number or by name (as given in
5297 .Va /usr/include/signal.h
5298 , stripped of the prefix
5305 does not send a signal
5307 If the signal being sent is TERM (terminate)
5308 or HUP (hangup), then the job or process is sent a
5309 CONT (continue) signal as well.
5310 The third form lists the signal names.
5319 Limits the consumption by the current process and each
5320 process it creates to not individually exceed
5328 the current limit is printed; if no
5331 all limitations are given.
5333 .Fl h\fR flag is given, the
5334 hard limits are used instead of the current limits.
5336 hard limits impose a ceiling on the values of the current
5338 Only the super-user may raise the hard limits, but
5339 a user may lower or raise the current limits within the legal range.
5341 Controllable resources currently include (if supported by the OS):
5342 .Bl -tag -width pseudoterminals -compact -offset indent
5344 the maximum number of cpu-seconds to be used by each process
5346 the largest single file which can be created
5348 the maximum growth of the data+stack region via sbrk(2) beyond
5349 the end of the program text
5351 the maximum size of the automatically-extended stack region
5353 the size of the largest core dump that will be created
5355 the maximum amount of physical memory a process
5356 may have allocated to it at a given time
5358 the maximum amount of virtual memory a process
5359 may have allocated to it at a given time (address space)
5361 the maximum amount of virtual memory a process
5362 may have allocated to it at a given time
5364 the maximum amount of memory a process
5371 the maximum number of open files for this process
5372 .It Va pseudoterminals
5373 the maximum number of pseudo-terminals for this user
5375 the maximum number of kqueues allocated for this process
5377 the maximum number of threads for this process
5379 the maximum size which a process may lock into memory using mlock(2)
5381 the maximum number of simultaneous processes for this user id
5383 the maximum number of simultaneous threads (lightweight processes) for this
5386 the maximum number of threads for this process
5388 the maximum size of socket buffer usage for this user
5390 the maximum amount of swap space reserved or used for this user
5392 the maximum number of locks for this user
5394 the maximum number of POSIX advisory locks for this user
5396 the maximum number of pending signals for this user
5398 the maximum number of bytes in POSIX mqueues for this user
5400 the maximum nice priority the user is allowed to raise mapped from [19...-20]
5401 to [0...39] for this user
5403 the maximum realtime priority for this user
5405 the timeout for RT tasks in microseconds for this user.
5409 may be given as a (floating point or
5410 integer) number followed by a scale factor.
5414 the default scale is
5418 (1024 bytes); a scale factor of
5429 the default scaling is
5435 for hours, or a time of the
5438 giving minutes and seconds may be used.
5444 then the limitation on the specified
5446 is removed (this is equivalent to the
5452 names and scale factors, unambiguous
5453 prefixes of the names suffice.
5459 shell variable and reports on each user indicated
5462 who is logged in, regardless of when they last logged in.
5467 Terminates a login shell, replacing it with an instance of
5469 . This is one way to log off, included for
5474 Terminates a login shell.
5475 Especially useful if
5487 It identifies each type of
5488 special file in the listing with a special character:
5489 .Bl -tag -width x -offset indent -compact
5499 Named pipe (systems with named pipes only)
5501 Socket (systems with sockets only)
5503 Symbolic link (systems with symbolic links only)
5505 Hidden directory (AIX only) or context dependent (HP/UX only)
5507 Network special (HP/UX only)
5512 shell variable is set, symbolic links are identified
5513 in more detail (on only systems that have them, of course):
5518 Symbolic link to a non-directory
5521 Symbolic link to a directory
5524 Symbolic link to nowhere
5528 also slows down \fIls\-F\fR and causes partitions holding
5529 files pointed to by symbolic links to be mounted.
5533 shell variable is set to
5540 combination thereof (e.g.,
5542 ), they are used as flags to \fIls\-F\fR,
5555 is not the default, \fIls\-F\fR acts like
5562 , in which case it acts like
5564 \fIls\-F\fR passes its arguments to
5566 (1) if it is given any switches,
5569 generally does the right thing.
5571 The \fBls\-F\fR builtin can list files using different colors depending on the
5572 filetype or extension.
5575 shell variable and the
5577 environment variable.
5593 The first form migrates the process or job to the site specified or the
5594 default site determined by the system path.
5595 The second form is equivalent to
5600 current process to the specified site.
5602 itself can cause unexpected behavior, because the shell
5603 does not like to lose its tty.
5616 Available only if the shell was so compiled;
5626 Sets the scheduling priority for the shell to
5641 The super-user may specify negative
5643 .Sq nice \-number ...
5645 executed in a sub-shell, and the restrictions placed on
5657 such that it will ignore hangup signals.
5658 Note that commands may set their own response to hangups, overriding
5660 Without an argument, causes the non-interactive shell only to
5661 ignore hangups for the remainder of the script.
5671 Causes the shell to notify the user asynchronously when the status of any
5672 of the specified jobs (or, without %
5674 , the current job) changes,
5675 instead of waiting until the next prompt as is usual.
5677 may be a number, a string,
5696 Controls the action of the shell on interrupts.
5698 restores the default action of the shell on interrupts,
5699 which is to terminate shell scripts or to return to the
5700 terminal command input level.
5703 , causes all interrupts to be ignored.
5706 , causes the shell to execute a
5709 when an interrupt is received or a child process terminates because it was
5713 is ignored if the shell is running detached and in system
5716 ), where interrupts are disabled anyway.
5725 Without arguments, pops the directory stack and returns to the new top directory.
5731 'th entry in the stack.
5733 Finally, all forms of
5735 print the final directory stack,
5740 shell variable can be set to
5741 prevent this and the
5742 .Fl p\fR flag can be given to override
5747 .Fl v\fR flags have the same effect on
5756 Prints the names and values of all environment variables or,
5759 , the value of the environment variable
5771 Without arguments, exchanges the top two elements of the directory stack.
5776 without arguments does
5784 , pushes the current working directory onto the directory
5785 stack and changes to
5791 it is interpreted as the previous working directory
5793 .Va Filename substitution
5800 removes any instances of
5802 from the stack before pushing it onto the stack.
5810 directory stack around to be the top element and changes to it.
5819 directory, pushes it onto the top of the stack and changes to it.
5822 Finally, all forms of
5824 print the final directory stack,
5829 shell variable can be set to
5830 prevent this and the
5831 .Fl p\fR flag can be given to override
5836 .Fl v\fR flags have the same effect on
5843 Causes the internal hash table of the contents of the
5846 variable to be recomputed.
5850 shell variable is not set and new
5851 commands are added to directories in
5853 while you are logged
5857 , a new command will be found
5858 automatically, except in the special case where another command of
5859 the same name which is located in a different directory already
5860 exists in the hash table.
5861 Also flushes the cache of home directories
5862 built by tilde expansion.
5864 .B repeat \fIcount command
5868 which is subject to the same restrictions as the
5872 statement above, is executed
5875 I/O redirections occur exactly once, even if
5882 Changes the rootnode to //
5904 The first form prints the scheduled-event list.
5907 shell variable may be set to define the format in which
5908 the scheduled-event list is printed.
5909 The second form adds
5911 to the scheduled-event list.
5916 > sched 11:00 echo It\e's eleven o\e'clock.
5918 causes the shell to echo
5919 .Sq It's eleven o'clock .
5921 The time may be in 12-hour AM/PM format
5924 > sched 5pm set prompt='[%h] It\e's after 5; go home: >'
5926 or may be relative to the current time:
5928 > sched +2:15 /usr/lib/uucp/uucico \-r1 \-sother
5930 A relative time specification may not use AM/PM format.
5931 The third form removes item
5933 from the event list:
5934 .Bd -literal -offset indent
5936 1 Wed Apr 4 15:42 /usr/lib/uucp/uucico \-r1 \-sother
5937 2 Wed Apr 4 17:00 set prompt=[%h] It's after 5; go home: >
5940 1 Wed Apr 4 15:42 /usr/lib/uucp/uucico \-r1 \-sother
5943 A command in the scheduled-event list is executed just before the first
5944 prompt is printed after the time when the command is scheduled.
5945 It is possible to miss the exact time when the command is to be run, but
5946 an overdue command will execute at the next prompt.
5947 A command which comes due while the shell
5948 is waiting for user input is executed immediately.
5949 However, normal operation of an already-running command will not
5950 be interrupted so that a scheduled-event list element may be run.
5952 This mechanism is similar to, but not the same as, the
5955 command on some Unix systems.
5956 Its major disadvantage is that it may not run a command at exactly the
5958 Its major advantage is that because
5961 the shell, it has access to shell variables and other structures.
5962 This provides a mechanism for changing one's working environment
5963 based on the time of day.
5978 .B set [\-r] [\-f|\-l]
6002 The first form of the command prints the value of all shell variables.
6003 Variables which contain more than a single word print as a
6004 parenthesized word list.
6005 The second form sets
6012 The fourth form sets
6014 to the list of words in
6016 In all cases the value is command and filename expanded.
6018 .Fl r\fR is specified, the value is set read-only.
6021 .Fl l\fR are specified, set only unique words keeping their order.
6022 .Fl f\fR prefers the first occurrence of a word, and
6024 The fifth form sets the
6031 this component must already exist.
6032 The sixth form lists only the names of all shell variables that are read-only.
6033 The seventh form makes
6035 read-only, whether or not it has a value.
6036 The eighth form is the same as the third form, but
6039 read-only at the same time.
6042 These arguments can be repeated to set and/or make read-only multiple variables
6043 in a single set command.
6044 Note, however, that variable expansion
6045 happens for all arguments before any setting occurs.
6053 or separated from both by
6054 whitespace, but cannot be adjacent to only one or the other.
6064 Without arguments, prints the names and values of all environment variables.
6067 , sets the environment variable
6073 , to the null string.
6083 .B setspath\fR LOCAL|
6089 Sets the system execution path.
6095 Tells the shell to believe that the terminal capability
6101 No sanity checking is done.
6102 Concept terminal users may have to
6105 wrapping at the rightmost column.
6117 Controls which tty modes (see
6118 .Va Terminal management
6120 the shell does not allow to change.
6132 set of tty modes respectively; without
6139 Without other arguments,
6141 lists the modes in the chosen set
6142 which are fixed on (`+mode') or off (`\-mode').
6143 The available modes, and thus the display, vary from system to system.
6145 .Fl a\fR, lists all tty modes in the chosen set
6146 whether or not they are fixed.
6157 or removes control from
6161 .Sq setty +echok echoe
6164 mode on and allows commands
6167 mode on or off, both when the shell is executing commands.
6172 Set the experimental version prefix to
6183 Without arguments, discards
6185 [1] and shifts the members of
6190 not to be set or to have
6191 less than one word as value.
6204 The shell reads and executes commands from
6206 The commands are not placed on the history list.
6209 are given, they are placed in
6213 commands may be nested;
6214 if they are nested too deeply the shell may run out of file descriptors.
6217 at any level terminates all nested
6221 .Fl h\fR, commands are placed on the history list instead of being
6230 Stops the specified jobs or processes which are executing in the background.
6232 may be a number, a string,
6251 Causes the shell to stop in its tracks, much as if it had
6252 been sent a stop signal with
6254 This is most often used to
6255 stop shells started by
6259 .B switch (\fIstring\fB)
6277 Each case label is successively matched, against the
6280 which is first command and filename expanded.
6281 The file metacharacters
6288 in the case labels, which are variable expanded.
6290 of the labels match before a
6292 label is found, then
6293 the execution begins after the default label.
6295 label and the default label must appear at the beginning of
6299 causes execution to continue
6302 Otherwise control may fall through case
6303 labels and default labels as in C.
6304 If no label matches and
6305 there is no default, execution continues after the
6310 Lists the values of all terminal capabilities (see
6319 (or the current value of
6323 is given) has an entry in the hosts termcap(5) or
6324 terminfo(5) database. Prints the terminal type to stdout and returns 0
6325 if an entry is present otherwise returns 1.
6332 (which must be a simple command, not an alias,
6333 a pipeline, a command list or a parenthesized command list)
6334 and prints a time summary as described under the
6337 If necessary, an extra shell is created to print the time statistic when
6338 the command completes.
6341 , prints a time summary for the current shell and its
6347 Sets the file creation mask to
6349 , which is given in octal.
6350 Common values for the mask are
6351 002, giving all access to the group and read and execute access to others, and
6352 022, giving read and execute access to the group and others.
6355 , prints the current file creation mask.
6360 Removes all aliases whose names match
6362 `unalias *' thus removes all aliases.
6363 It is not an error for nothing to be
6370 Removes all completions whose names match
6372 `uncomplete *' thus removes all completions.
6373 It is not an error for nothing to be
6378 Disables use of the internal hash table to speed location of
6384 Sets the universe to
6392 Removes the limitation on
6401 .Fl h\fR, the corresponding hard limits are removed.
6402 Only the super-user may do this.
6405 may not exit successful, since most systems
6410 .Fl f\fR errors are ignored.
6413 Removes all variables whose names match
6415 , unless they are read-only.
6416 `unset *' thus removes all variables unless they are read-only;
6418 It is not an error for nothing to be
6421 .B unsetenv \fIpattern
6422 Removes all environment variables whose names match
6424 `unsetenv *' thus removes all environment variables;
6426 It is not an error for nothing to be
6435 Without arguments, prints
6459 The shell waits for all background jobs.
6460 If the shell is interactive, an
6461 interrupt will disrupt the wait and cause the shell to print the names and job
6462 numbers of all outstanding jobs.
6467 Sets the universe to
6472 An alternate name for the
6474 builtin command (q.v.).
6475 Available only if the shell was so compiled;
6483 Reports all known instances of
6485 , including aliases, builtins and
6492 Displays the command that will be executed by the shell after substitutions,
6495 The builtin command is just like
6497 (1), but it correctly reports
6499 aliases and builtins and is 10 to 100 times faster.
6511 Executes the commands between the
6517 (an expression, as described under
6524 must appear alone on their input lines.
6528 may be used to terminate or continue the
6530 If the input is a terminal, the user is prompted the first time
6531 through the loop as with
6534 .Ss "Special aliases (+)"
6535 If set, each of these aliases executes automatically at the indicated time.
6536 They are all initially undefined.
6539 Runs when the shell wants to ring the terminal bell.
6542 Runs after every change of working directory.
6543 For example, if the user is
6544 working on an X window system using
6546 (1) and a re-parenting window
6547 manager that supports title bars such as
6552 > alias cwdcmd 'echo \-n "^[]2;${HOST}:$cwd ^G"'
6554 then the shell will change the title of the running
6557 to be the name of the host, a colon, and the full current working directory.
6558 A fancier way to do that is
6560 > alias cwdcmd 'echo \-n "^[]2;${HOST}:$cwd^G^[]1;${HOST}^G"'
6562 This will put the hostname and working directory on the title bar but
6563 only the hostname in the icon manager menu.
6573 may cause an infinite loop.
6574 It is the author's opinion that anyone doing
6575 so will get what they deserve.
6579 Runs before each command gets executed, or when the command changes state.
6582 , but it does not print builtins.
6585 > alias jobcmd 'echo \-n "^[]2\e;\e!#:q^G"'
6589 will put the command string in the xterm title bar.
6596 The command name for which help
6597 is sought is passed as sole argument.
6598 For example, if one does
6601 > alias helpcommand '\e!:1 --help'
6603 then the help display of the command itself will be invoked, using the GNU
6604 help calling convention.
6605 Currently there is no easy way to account for various calling conventions (e.g.,
6608 ), except by using a table of many commands.
6615 This provides a convenient means for
6616 checking on common but infrequent changes such as new mail.
6623 > alias periodic checknews
6627 (1) program runs every 30 minutes.
6632 is unset or set to 0,
6639 Runs just before each prompt is printed.
6640 For example, if one does
6647 (1) runs just before the shell prompts for each command.
6648 There are no limits on what
6650 can be set to do, but discretion
6655 Runs before each command gets executed.
6658 > alias postcmd 'echo \-n "^[]2\e;\e!#:q^G"'
6662 will put the command string in the xterm title bar.
6666 Specifies the interpreter for executable scripts which do not themselves
6667 specify an interpreter.
6668 The first word should be a full path name to the
6669 desired interpreter (e.g.,
6672 .Sq /usr/local/bin/tcsh
6674 .Ss "Special shell variables"
6675 The variables described in this section have special meaning to the shell.
6704 startup; they do not change thereafter unless changed by the user.
6716 The shell synchronizes
6723 with the environment variables of the same names:
6724 whenever the environment variable changes the shell changes the corresponding
6725 shell variable to match (unless the shell variable is read-only) and vice
6731 have identical meanings, they
6732 are not synchronized in this manner, and that the shell automatically
6733 converts between the different formats of
6739 If set, filename completion adds
6741 to the end of directories and a space
6742 to the end of normal files when they are matched exactly.
6748 's autolock feature uses its value instead of
6749 the local username for kerberos authentication.
6752 If set, all times are shown in 12-hour AM/PM format.
6755 This variable selects what is propagated to the value of the
6757 variable. For more information see the description of the
6762 The arguments to the shell.
6763 Positional parameters are taken from
6771 Set by default, but usually empty in interactive shells.
6773 .B autocorrect \fR(+)
6776 editor command is invoked automatically before
6777 each completion attempt.
6779 .B autoexpand \fR(+)
6782 editor command is invoked automatically
6783 before each completion attempt. If this is set to
6786 only history will be expanded and a second completion will expand filenames.
6789 If set, possibilities are listed after an ambiguous completion.
6792 , possibilities are listed only when no new
6793 characters are added by completion.
6795 .B autologout \fR(+)
6796 The first word is the number of minutes of inactivity before automatic
6798 The optional second word is the number of minutes of inactivity
6799 before automatic locking.
6800 When the shell automatically logs out, it prints
6808 When the shell automatically locks, the user is required to enter his password
6809 to continue working.
6810 Five incorrect attempts result in automatic logout.
6813 (automatic logout after 60 minutes, and no locking) by default
6814 in login and superuser shells, but not if the shell thinks it is running
6815 under a window system (i.e., the
6817 environment variable is set),
6818 the tty is a pseudo-tty (pty) or the shell was not so compiled (see the
6822 .Va autologout or set it to
6824 to disable automatic logout.
6831 .B autorehash \fR(+)
6832 If set, the internal hash table of the contents of the directories in the
6834 variable will be recomputed if a command is not found in the hash
6836 In addition, the list of available commands will be rebuilt for each
6837 command completion or spelling correction attempt if set to
6840 `correct' respectively; if set to
6842 , this will be done for both
6845 .B backslash_quote \fR(+)
6847 If set, backslashes (`\e') always quote
6854 complex quoting tasks easier, but it can cause syntax errors in
6859 The file name of the message catalog.
6862 as a message catalog instead of
6867 A list of directories in which
6870 subdirectories if they aren't found in the current directory.
6875 requires a directory
6877 , and will not go to the
6879 directory if it's omitted.
6880 This is set by default.
6883 If set, it enables color display for the builtin \fBls\-F\fR and it passes
6884 .Fl \-color=auto\fR to
6886 Alternatively, it can be set to only
6889 to enable color to only one command.
6891 it to nothing is equivalent to setting it to \fB(ls\-F ls)\fR.
6894 If set, it enables color escape sequence for NLS message files.
6895 And display colorful NLS messages.
6898 If set, the command which was passed to the shell with the
6902 .B compat_expr \fR(+)
6903 If set, the shell will evaluate expressions right to left, like the original
6909 , the completion becomes case insensitive.
6912 , completion ignores case and considers
6913 hyphens and underscores to be equivalent; it will also treat
6914 periods, hyphens and underscores (`.',
6922 , completion matches uppercase and underscore
6923 characters explicitly and matches lowercase and hyphens in a
6924 case-insensitive manner; it will treat periods, hyphens and underscores
6928 If set to a list of commands, the shell will continue the listed
6929 commands, instead of starting a new one.
6931 .B continue_args \fR(+)
6932 Same as continue, but the shell will execute:
6935 echo \`pwd\` $argv > ~/.<cmd>_pause; %<cmd>
6941 , commands are automatically spelling-corrected.
6944 , commands are automatically completed.
6947 , the entire command line is corrected.
6949 .B csubstnonl \fR(+)
6950 If set, newlines and carriage returns in command substitution are
6955 The full pathname of the current directory.
6968 th directory from the directory
6969 stack rather than rotating it to the top.
6972 The default location in which
6983 is normally sourced before
6993 An array of all the directories on the directory stack.
6994 `$dirstack[1]' is the current working directory,
6996 the first directory on the stack, etc.
6997 Note that the current working directory is
7002 directory stack substitutions, etc.
7003 One can change the stack arbitrarily by setting
7006 but the first element (the current working directory) is always correct.
7014 Has an effect iff 'dspm' is listed as part of the
7019 , it enables display and editing EUC-kanji(Japanese) code.
7022 , it enables display and editing Shift-JIS(Japanese) code.
7025 , it enables display and editing Big5(Chinese) code.
7028 , it enables display and editing Utf8(Unicode) code.
7029 If set to the following format, it enables display and editing of original
7030 multi-byte code format:
7033 > set dspmbyte = 0000....(256 bytes)....0000
7038 Each character of 256 characters
7039 corresponds (from left to right) to the ASCII codes 0x00, 0x01, ... 0xff.
7042 .\" (position in this table?)
7043 is set to number 0,1,2 and 3.
7044 Each number has the following meaning:
7046 0 ... not used for multi-byte characters.
7048 1 ... used for the first byte of a multi-byte character.
7050 2 ... used for the second byte of a multi-byte character.
7052 3 ... used for both the first byte and second byte of a multi-byte character.
7053 .\" SHK: I tried my best to get the following to be grammatically correct.
7054 .\" However, I still don't understand what's going on here.
7056 .\" following example, there are three bytes, but the text seems to refer to
7057 .\" each nybble as a character.
7058 What's going on here? It this 3-byte code
7059 .\" in the table? The text above seems to imply that there are 256
7060 .\" characters/bytes in the table.
7061 If I get some more info on this (perhaps
7062 .\" a complete example), I could fix the text to be grammatically correct.
7063 .\" (steve.kelem@xilinx.com 1999/09/13)
7069 , the first character (means 0x00 of the ASCII code) and
7070 second character (means 0x01 of ASCII code) are set to
7073 used for multi-byte characters.
7074 The 3rd character (0x02) is set to '1',
7075 indicating that it is used for the first byte of a multi-byte character.
7076 The 4th character(0x03) is set '3'.
7077 It is used for both the first byte and
7078 the second byte of a multi-byte character.
7079 The 5th and 6th characters
7080 (0x04,0x05) are set to '2', indicating that they are used for the second
7081 byte of a multi-byte character.
7083 The GNU fileutils version of ls cannot display multi-byte
7084 filenames without the -N ( --literal ) option.
7086 this version, set the second word of dspmbyte to "ls".
7088 example, "ls-F -l" cannot display multi-byte filenames.
7092 This variable can only be used if KANJI and DSPMBYTE has been defined at
7099 removes any instances of
7101 from the stack before pushing it onto the stack.
7104 If set, each command with its arguments is echoed just before it is
7106 For non-builtin commands all expansions occur before
7108 Builtin commands are echoed before command and filename
7109 substitution, because these substitutions are then done selectively.
7111 .Fl x\fR command line option.
7113 .B echo_style \fR(+)
7123 Don't echo a newline if the first argument is
7129 Recognize backslashed escape sequences in echo strings.
7134 flag and backslashed escape sequences; the default
7142 Set by default to the local system default.
7143 The BSD and System V
7144 options are described in the
7146 (1) man pages on the appropriate
7151 If set, the command-line editor is used.
7152 Set by default in interactive
7156 A list of command names for the
7158 editor command to match.
7164 environment variables will be used instead.
7171 prompt sequences (see the
7173 shell variable) indicate skipped directories with an ellipsis (`...')
7178 The user's effective user ID.
7181 The first matching passwd entry name corresponding to the effective user ID.
7184 Lists file name suffixes to be ignored by completion.
7189 , completion is always used and this variable is ignored
7192 is unset, then the traditional
7197 , filename completion is used.
7200 The user's real group ID.
7203 If set, wild-card glob patterns will match files and directories beginning
7216 file glob patterns will match any string of
7217 characters including
7219 traversing any existing sub-directories.
7221 `ls **.c' will list all the .c files in the current directory tree).
7222 If used by itself, it will match zero or more sub-directories
7224 .Sq ls /usr/include/**/time.h
7225 will list any file named
7227 in the /usr/include directory tree; whereas
7228 .Sq ls /usr/include/**time.h
7229 will match any file in the /usr/include directory tree ending in
7232 To prevent problems with recursion, the
7234 glob-pattern will not
7235 descend into a symbolic link containing a directory.
7241 The user's group name.
7244 If set, the incremental search match (in
7248 ) and the region between the mark and the cursor are
7249 highlighted in reverse video.
7251 Highlighting requires more frequent terminal writes, which introduces extra
7252 overhead. If you care about terminal performance, you may want to leave this
7256 A string value determining the characters used in \fBHistory
7257 substitution\fR (q.v.).
7258 The first character of its value is used as
7259 the history substitution character, replacing the default character
7261 The second character of its value replaces the character
7264 quick substitutions.
7267 Controls handling of duplicate entries in the history list.
7269 `all' only unique history events are entered in the history list.
7273 and the last history event is the same as the current
7274 command, then the current command is not entered in the history.
7278 and the same event is found in the history list, that
7279 old event gets erased and the current one gets inserted.
7283 options renumber history events so there are no gaps.
7286 The default location in which
7297 useful when sharing the same home directory between different machines,
7298 or when saving separate histories on different terminals.
7301 is normally sourced before
7311 If set, builtin and editor commands and the
7314 use the literal (unexpanded) form of lines in the history list.
7317 .Va toggle-literal-history
7321 The first word indicates the number of history events to save.
7323 optional second word (+) indicates the format in which history is
7324 printed; if not given,
7327 The format sequences
7328 are described below under
7330 ; note the variable meaning of
7337 Initialized to the home directory of the invoker.
7342 refers to this variable.
7345 If set to the empty string or
7347 and the input device is a terminal,
7350 command (usually generated by the user by typing
7351 `^D' on an empty line) causes the shell to print `Use "exit" to leave
7352 tcsh.' instead of exiting.
7353 This prevents the shell from accidentally
7355 Historically this setting exited after 26 successive
7356 EOF's to avoid infinite loops.
7369 is used, i.e., the shell exits on a
7373 .B implicitcd \fR(+)
7374 If set, the shell treats a directory name typed as a command as though
7375 it were a request to change to that directory.
7379 the change of directory is echoed to the standard output.
7381 is inhibited in non-interactive shell scripts, or for command strings
7382 with more than one word.
7383 Changing directory takes precedence over
7384 executing a like-named command, but it is done after alias
7386 Tilde and variable expansions work as expected.
7393 , puts the editor into that input mode
7394 at the beginning of each line.
7397 Controls handling of duplicate entries in the kill ring.
7399 `all' only unique strings are entered in the kill ring.
7401 `prev' and the last killed string is the same as the current killed
7402 string, then the current string is not entered in the ring.
7406 and the same string is found in the kill ring, the old
7407 string is erased and the current one is inserted.
7410 Indicates the number of killed strings to keep in memory.
7414 If unset or set to less than
7416 , the shell will only
7417 keep the most recently killed string.
7418 Strings are put in the killring by the editor commands that delete
7419 (kill) strings of text, e.g.
7420 .Va backward-delete-word
7423 , etc, as well as the
7424 .Va copy-region-as-kill
7428 editor command will yank the most recently killed string
7429 into the command-line, while
7434 can be used to yank earlier killed strings.
7443 , or any combination thereof (e.g.,
7446 are used as flags to \fIls\-F\fR, making it act like
7451 or a combination (e.g.,
7456 files (even if they start with a
7465 sorts across instead of down.
7466 If the second word of
7468 is set, it is used as the path to
7472 If set, all jobs are listed when a job is suspended.
7476 the listing is in long format.
7479 If set, the \fIls\-F\fR builtin command shows the type of file to which
7480 each symbolic link points.
7483 The maximum number of items which the
7486 will list without asking first.
7488 .B listmaxrows \fR(+)
7489 The maximum number of rows of items which the
7492 command will list without asking first.
7495 Set by the shell if it is a login shell.
7496 Setting or unsetting it
7497 within a shell has no effect.
7504 before a normal logout,
7507 an automatic logout, and
7509 if the shell was killed by a hangup
7518 A list of files and directories to check for incoming mail, optionally
7519 preceded by a numeric word.
7520 Before each prompt, if 10 minutes have
7521 passed since the last check, the shell checks each file and says `You
7522 have new mail.' (or, if
7524 contains multiple files, `You have
7527 .') if the filesize is greater than zero in size
7528 and has a modification time greater than its access time.
7533 If you are in a login shell, then no mail file is reported unless it has
7534 been modified after the time the shell has started up, to prevent
7535 redundant notifications.
7536 Most login programs will tell you whether or not
7537 you have mail when you log in.
7539 If a file specified in
7541 is a directory, the shell will count each
7542 file within that directory as a separate message, and will report `You have
7550 This functionality is provided primarily for those systems which store mail
7551 in this manner, such as the Andrew Mail System.
7553 If the first word of
7555 is numeric it is taken as a different mail
7556 checking interval, in seconds.
7558 Under very rare circumstances, the shell may report
7562 .Sq You have new mail.
7568 , completion never beeps.
7571 , it beeps only when there is no match.
7574 , it beeps when there are multiple matches.
7577 , it beeps when there is one exact and other longer matches.
7583 If set, beeping is completely disabled.
7588 If set, restrictions are placed on output redirection to insure that files
7589 are not accidentally destroyed and that
7591 redirections refer to existing
7592 files, as described in the
7597 If set, disable the printing of
7602 specifiers at the change of hour.
7606 .Va Filename substitution
7608 .Va Directory stack substitution
7609 (q.v.) are inhibited.
7610 This is most useful in shell scripts which do not deal
7611 with filenames, or after a list of filenames has been obtained and further
7612 expansions are not desirable.
7615 If set and the shell supports Kanji (see the
7618 it is disabled so that the meta key can be used.
7622 .Va Filename substitution
7624 .Va Directory stack substitution
7625 (q.v.) which does not match any
7626 existing files is left untouched rather than causing an error.
7627 It is still an error for the substitution to be
7630 still gives an error.
7633 A list of directories (or glob-patterns which match directories; see
7634 .Va Filename substitution
7635 ) that should not be
7638 completion operation.
7639 This is usually used to exclude directories which
7640 take too much time to
7646 If set, the shell announces job completions asynchronously.
7647 The default is to present job completions just before printing a prompt.
7650 The user's real organization ID.
7654 The old working directory, equivalent to the
7667 If set, enable the printing of padding '0' for hours, in 24 and 12 hour
7669 E.G.: 07:45:42 vs. 7:45:42.
7672 To retain compatibily with older versions numeric variables starting with
7673 0 are not interpreted as octal. Setting this variable enables proper octal
7677 A list of directories in which to look for executable commands.
7678 A null word specifies the current directory.
7681 variable then only full path names will execute.
7683 is set by the shell at startup from the
7688 does not exist, to a system-dependent default
7690 .Sq (/usr/local/bin /usr/bsd /bin /usr/bin .)
7696 depending on how it was compiled; see the
7699 A shell which is given neither the
7702 hashes the contents of the directories in
7710 If one adds a new command to a directory in
7713 is active, one may need to do a
7715 for the shell to find it.
7717 .B printexitvalue \fR(+)
7718 If set and an interactive program exits with a non-zero status, the shell
7724 The string which is printed before reading each command from the terminal.
7726 may include any of the following formatting sequences (+), which
7727 are replaced by the given information:
7733 The current working directory.
7736 The current working directory, but with one's home directory
7739 and other users' home directories represented by
7741 .Va Filename substitution
7742 `~user' substitution
7743 happens only if the shell has already used
7747 in the current session.
7754 The trailing component of the current working directory, or
7756 trailing components if a digit
7763 , the number of skipped components precede
7764 the trailing component(s) in the format
7770 shell variable is set, skipped components
7771 are represented by an ellipsis so the whole becomes
7773 `~' substitution is done as in
7778 is ignored when counting trailing components.
7781 Like %c, but without
7786 The current history event number.
7792 The hostname up to the first
7796 Start (stop) standout mode.
7799 Start (stop) boldfacing mode.
7802 Start (stop) underline mode.
7805 The time of day in 12-hour AM/PM format.
7810 , but in 24-hour format (but see the
7817 time of day in 12-hour AM/PM format, with seconds.
7822 , but in 24-hour format (but see the
7846 The effective user name.
7885 Clears from the end of the prompt to end of the display or the end of the line.
7888 Expands the shell or environment variable name immediately after the
7892 `>' (or the first character of the
7897 (or the second character of
7907 as a literal escape sequence.
7908 It should be used only to change terminal attributes and
7909 should not move the cursor location.
7911 cannot be the last sequence in
7915 The return code of the command executed just before the prompt.
7920 , the status of the parser.
7923 , the corrected string.
7926 , the history string.
7937 are available in only
7938 eight-bit-clean shells; see the
7942 The bold, standout and underline sequences are often used to distinguish a
7946 > set prompt = "%m [%h] %B[%@]%b [%/] you rang? "
7950 [/usr/accts/sys] you rang? _
7967 on the change of hour (i.e,
7974 in interactive shells.
7978 The string with which to prompt in
7983 after lines ending in
7985 The same format sequences may be used as in
7988 note the variable meaning of
7992 in interactive shells.
7995 The string with which to prompt when confirming automatic spelling correction.
7996 The same format sequences may be used as in
7999 note the variable meaning of
8002 .Sq CORRECT>%R (y|n|e|a)?
8003 in interactive shells.
8005 .B promptchars \fR(+)
8006 If set (to a two-character string), the
8008 formatting sequence in the
8010 shell variable is replaced with the first character for
8011 normal users and the second character for the superuser.
8013 .B pushdtohome \fR(+)
8016 without arguments does
8021 .B pushdsilent \fR(+)
8026 do not print the directory stack.
8029 If set, completion completes on an exact match even if a longer match is
8032 .B recognize_only_executables \fR(+)
8033 If set, command listing displays only files in the path that are
8038 If set, the user is prompted before
8043 The string to print on the right-hand side of the screen (after
8044 the command input) when the prompt is being displayed on the left.
8045 It recognizes the same formatting characters as
8047 It will automatically disappear and reappear as necessary, to ensure that
8048 command input isn't obscured, and will appear only if the prompt,
8049 command input, and itself will fit together on the first line.
8054 will be printed after
8055 the prompt and before the command input.
8058 If set, the shell does
8061 If the first word is set to a number, at most that many directory stack
8065 If set, the shell does
8068 If the first word is set to a number, at most that many lines are saved.
8069 (The number should be less than or equal to the number
8072 if it is set to greater than the number of
8076 entries will be saved)
8077 If the second word is set to
8079 , the history list is merged with
8080 the existing history file instead of replacing it (if there is one) and
8081 sorted by time stamp and the most recent events are retained.
8082 If the second word of
8086 and the third word is set to
8087 `lock', the history file update will be serialized with other shell sessions
8088 that would possibly like to merge history at exactly the same time. (+)
8091 The format in which the
8093 builtin command prints scheduled events;
8097 The format sequences are described above under
8100 note the variable meaning of
8104 The file in which the shell resides.
8105 This is used in forking
8106 shells to interpret files which have execute bits set, but
8107 which are not executable by the system.
8108 (See the description
8110 .Va Builtin and non-builtin command execution
8111 .) Initialized to the
8112 (system-dependent) home of the shell.
8115 The number of nested shells.
8116 Reset to 1 in login shells.
8121 The exit status from the last command or backquote expansion, or any
8122 command in a pipeline is propagated to
8128 This default does not match what POSIX mandates (to return the
8129 status of the last command only). To match the POSIX behavior, you need
8136 variable is unset, the exit status of a pipeline
8137 is determined only from the last command in the pipeline, and the exit
8138 status of a backquote expansion is
8143 If a command terminated abnormally, then 0200 is added to the status.
8144 Builtin commands which fail return exit status
8147 commands return status
8152 Can be set to several different values to control symbolic link (`symlink')
8158 , whenever the current directory changes to a directory
8159 containing a symbolic link, it is expanded to the real name of the directory
8160 to which the link points.
8161 This does not work for the user's home directory;
8166 , the shell tries to construct a current directory
8167 relative to the current directory before the link was crossed.
8170 ing through a symbolic link and then
8173 returns one to the original directory.
8174 This affects only builtin commands
8175 and filename completion.
8179 , the shell tries to fix symbolic links by actually expanding
8180 arguments which look like path names.
8181 This affects any command, not just
8183 Unfortunately, this does not work for hard-to-recognize filenames,
8184 such as those embedded in command options.
8185 Expansion may be prevented by
8187 While this setting is usually the most convenient, it is sometimes
8188 misleading and sometimes confusing when it fails to recognize an argument
8189 which should be expanded.
8190 A compromise is to use
8195 (bound by default to ^X-n) when necessary.
8197 Some examples are in order.
8198 First, let's set up some play directories:
8202 > mkdir from from/src to
8204 > ln \-s from/src to/dst
8206 Here's the behavior with
8210 > cd /tmp/to/dst; echo $cwd
8218 here's the behavior with
8224 > cd /tmp/to/dst; echo $cwd
8232 here's the behavior with
8238 > cd /tmp/to/dst; echo $cwd
8246 and here's the behavior with
8251 > cd /tmp/to/dst; echo $cwd
8259 > cd /tmp/to/dst; echo $cwd
8263 > cd ".."; echo $cwd
8277 expansion 1) works just like
8282 , 2) is prevented by quoting, and 3) happens before
8283 filenames are passed to non-builtin commands.
8287 The version number of the shell in the format
8292 is the major release number,
8304 .Va Startup and shutdown
8307 If set to a number, then the
8309 builtin (q.v.) executes automatically
8310 after each command which takes more than that many CPU seconds.
8311 If there is a second word, it is used as a format string for the output
8315 (u) The following sequences may be used in the
8322 The time the process spent in user mode in cpu seconds.
8325 The time the process spent in kernel mode in cpu seconds.
8328 The elapsed (wall clock) time in seconds.
8331 The CPU percentage computed as (%U + %S) / %E.
8334 Number of times the process was swapped.
8337 The average amount in (shared) text space used in Kbytes.
8340 The average amount in (unshared) data/stack space used in Kbytes.
8343 The total space used (%X + %D) in Kbytes.
8346 The maximum memory the process had in use at any time in Kbytes.
8349 The number of major page faults (page needed to be brought from disk).
8352 The number of minor page faults.
8355 The number of input operations.
8358 The number of output operations.
8361 The number of socket messages received.
8364 The number of socket messages sent.
8367 The number of signals received.
8370 The number of voluntary context switches (waits).
8373 The number of involuntary context switches.
8376 Only the first four sequences are supported on systems without BSD resource
8378 The default time format is
8379 .Sq %Uu %Ss %E %P %X+%Dk %I+%Oio %Fpf+%Ww
8381 systems that support resource usage reporting and
8384 systems that do not.
8386 Under Sequent's DYNIX/ptx, %X, %D, %K, %r and %s are not
8387 available, but the following additional sequences are:
8392 The number of system calls performed.
8395 The number of pages which are zero-filled on demand.
8398 The number of times a process's resident set size was increased by the kernel.
8401 The number of times a process's resident set size was decreased by the kernel.
8404 The number of read system calls performed.
8407 The number of write system calls performed.
8410 The number of reads from raw disk devices.
8413 The number of writes to raw disk devices.
8416 and the default time format is
8417 .Sq %Uu %Ss %E %P %I+%Oio %Fpf+%Ww
8418 Note that the CPU percentage can be higher than 100% on multi-processors.
8422 The period, in minutes, between executions of the
8427 The name of the tty, or empty if not attached to one.
8430 The user's real user ID.
8433 The user's login name.
8436 If set, causes the words of each
8437 command to be printed, after history substitution (if any).
8439 .Fl v\fR command line option.
8442 The version ID stamp.
8443 It contains the shell's version number (see
8446 origin, release date, vendor, operating system and machine (see
8452 ) and a comma-separated
8453 list of options which were set at compile time.
8454 Options which are set by default in the distribution are noted.
8460 The shell is eight bit clean; default
8463 The shell is not eight bit clean
8466 The shell is multibyte encoding clean (like UTF-8)
8469 The system's NLS is used; default for systems with NLS
8472 Login shells execute
8474 before instead of after
8478 before instead of after
8486 for security; default
8495 (1)\-style editing is the default rather than
8500 Login shells drop DTR when exiting
8508 is an alternate name for
8516 Kanji is used if appropriate according to locale settings,
8519 shell variable is set
8528 .Sq #!<program> <args>
8529 convention is emulated when executing shell scripts
8534 builtin is available
8537 The shell attempts to set the
8539 environment variable
8542 The shell verifies your password with the kerberos server if local
8543 authentication fails.
8546 shell variable or the
8548 environment variable override your local username if set.
8551 An administrator may enter additional strings to indicate differences
8552 in the local version.
8557 If unset, various key bindings change behavior to be more
8560 word boundaries are determined by
8562 versus other characters.
8564 If set, various key bindings change behavior to be more
8567 word boundaries are determined by
8570 versus other characters;
8571 cursor behavior depends upon current vi mode (command, delete, insert, replace).
8573 This variable is unset by
8583 may be explicitly set or unset by the user after those
8585 operations if required.
8588 .B visiblebell \fR(+)
8589 If set, a screen flash is used rather than the audible bell.
8594 A list of user/terminal pairs to watch for logins and logouts.
8595 If either the user is
8597 all terminals are watched for the given user
8603 watches all users and terminals.
8607 set watch = (george ttyd1 any console $user any)
8609 reports activity of the user
8611 on ttyd1, any user on the console, and
8612 oneself (or a trespasser) on any terminal.
8614 Logins and logouts are checked every 10 minutes by default, but the first
8617 can be set to a number to check every so many minutes.
8620 set watch = (1 any any)
8622 reports any login/logout once every minute.
8623 For the impatient, the
8625 builtin command triggers a
8629 are reported (as with the
8637 shell variable controls the format of
8643 The format string for
8646 The following sequences
8647 are replaced by the given information:
8653 The name of the user who logged in/out.
8656 The observed action, i.e.,
8666 The terminal (tty) on which the user logged in/out.
8669 The full hostname of the remote host, or
8671 if the login/logout was
8672 from the local host.
8675 The hostname of the remote host up to the first
8677 The full name is printed if it is an IP address or an X Window System display.
8680 %M and %m are available on only systems that store the remote hostname in
8683 .Sq %n has %a %l from %m.
8687 which don't store the remote hostname.
8691 A list of non-alphanumeric characters to be considered part of a word by the
8695 etc., editor commands.
8696 If unset, the default value is determined based on the state of
8703 is used as the default;
8708 is used as the default.
8717 The number of columns in the terminal.
8719 .Va Terminal management
8722 Used by X Window System (see
8725 If set, the shell does not set
8730 The pathname to a default editor.
8733 editor command if the
8736 shell variable is unset.
8739 environment variable.
8752 Initialized to the name of the machine on which the shell
8753 is running, as determined by the
8758 Initialized to the type of machine on which the shell
8759 is running, as determined at compile time.
8760 This variable is obsolete and
8761 will be removed in a future version.
8764 A colon-separated list of directories in which the
8767 command looks for command documentation.
8770 Gives the preferred character environment.
8772 .Va Native Language System support
8775 If set, only ctype character handling is changed.
8777 .Va Native Language System support
8780 The number of lines in the terminal.
8782 .Va Terminal management
8785 The format of this variable is reminiscent of the
8787 file format; a colon-separated list of expressions of the form
8792 " is a two-character variable name.
8794 variables with their associated defaults are:
8801 Normal (non-filename) text
8831 Missing file (defaults to fi)
8834 Orphaned symbolic link (defaults to ln)
8843 End code (replaces lc+no+rc)
8847 You need to include only the variables you want to change from
8850 File names can also be colorized based on filename extension.
8851 This is specified in the
8853 variable using the syntax
8855 For example, using ISO 6429 codes, to color
8856 all C\-language source files blue you would specify
8858 This would color all files ending in
8862 Control characters can be written either in C\-style\-escaped
8863 notation, or in stty\-like ^\-notation.
8864 The C\-style notation
8867 for Escape, \fB\_\fR for a normal space character,
8874 can be used to override the default interpretation of
8883 Each file will be written as
8894 code is undefined, the sequence
8898 will be used instead.
8899 This is generally more convenient
8900 to use, but less general.
8901 The left, right and end codes are
8902 provided so you don't have to type common parts over and over
8903 again and to support weird terminals; you will generally not
8904 need to change them at all unless your terminal does not use
8905 ISO 6429 color sequences but a different system.
8907 If your terminal does use ISO 6429 color codes, you can
8908 compose the type codes (i.e., all except the
8915 codes) from numerical commands separated by semicolons.
8917 most common commands are:
8923 to restore default color
8935 for black foreground
8941 for green foreground
8944 for yellow (or brown) foreground
8950 for purple foreground
8956 for white (or gray) foreground
8959 for black background
8965 for green background
8968 for yellow (or brown) background
8974 for purple background
8980 for white (or gray) background
8984 Not all commands will work on all systems or display devices.
8986 A few terminal programs do not recognize the default end code
8988 If all text gets colorized after you do a directory
8989 listing, try changing the
8994 numerical codes for your standard fore- and background colors.
8998 The machine type (microprocessor class or machine model), as determined at compile time.
9001 If set, printable characters are not rebound to
9002 .Va self-insert-command
9004 .Va Native Language System support
9007 The operating system, as determined at compile time.
9010 A colon-separated list of directories in which to look for executables.
9013 shell variable, but in a different format.
9018 shell variable, but not synchronized to it;
9019 updated only after an actual directory change.
9021 .B REMOTEHOST \fR(+)
9022 The host from which the user has logged in remotely, if this is the case and
9023 the shell is able to determine it.
9024 Set only if the shell was so compiled;
9035 The current system type.
9044 The terminal capability string.
9046 .Va Terminal management
9054 The vendor, as determined at compile time.
9057 The pathname to a default full-screen editor.
9060 editor command if the
9063 shell variable is unset.
9066 environment variable.
9071 Read first by every shell.
9072 ConvexOS, Stellix and Intel use
9077 A/UX, AMIX, Cray and IRIX have no equivalent in
9080 but read this file in
9083 Solaris 2.x does not have it either, but
9090 Read by login shells after
9092 ConvexOS, Stellix and Intel use
9100 A/UX, AMIX, Cray and IRIX use
9104 Read by every shell after
9109 Read by every shell, if
9128 Read by login shells after
9132 is set, but see also
9136 Read by login shells after
9140 The shell may be compiled to read
9142 before instead of after
9150 .I ~/.cshdirs \fR(+)
9151 Read by login shells after
9155 is set, but see also
9159 Read by login shells at logout.
9160 ConvexOS, Stellix and Intel use
9165 A/UX, AMIX, Cray and IRIX have no equivalent in
9168 but read this file in
9171 Solaris 2.x does not have it either, but
9178 Read by login shells at logout after
9183 Used to interpret shell scripts not starting with a
9191 Source of home directories for
9196 The order in which startup files are read may differ if the shell was so
9198 .Va Startup and shutdown
9202 .Sh "NEW FEATURES (+)"
9203 This manual describes
9208 users will want to pay special attention to
9212 A command-line editor, which supports
9217 (1)\-style key bindings.
9219 .Va The command-line editor
9223 Programmable, interactive word completion and listing.
9225 .Sx Completion and listing
9232 .Va Spelling correction
9233 (q.v.) of filenames, commands and variables.
9236 (q.v.) which perform other useful functions in the middle of
9237 typed commands, including documentation lookup
9239 quick editor restarting
9240 .Va ( run-fg-editor )
9243 .Va ( which-command ).
9245 An enhanced history mechanism.
9246 Events in the history list are time-stamped.
9249 command and its associated shell variables,
9250 the previously undocumented
9252 event specifier and new modifiers
9254 .Va History substitution
9259 .Va history-search-*
9265 .Va toggle-literal-history
9271 Enhanced directory parsing and directory stack handling.
9280 commands and their associated
9281 shell variables, the description of
9282 .Va Directory stack substitution
9292 .Va normalize-command
9297 Negation in glob-patterns.
9299 .Va Filename substitution
9302 .Va File inquiry operators
9305 builtin which uses them.
9308 .Va Automatic, periodic and timed events
9310 scheduled events, special aliases, automatic logout and terminal locking,
9311 command timing and watching for logins and logouts.
9313 Support for the Native Language System
9315 .Va Native Language System support
9319 .Va OS variant support
9323 and system-dependent file locations (see
9327 Extensive terminal-management capabilities.
9329 .Va Terminal management
9331 New builtin commands including
9345 New variables that make useful information easily available to the shell.
9362 shell variables and the
9375 A new syntax for including useful information in the prompt string
9379 and special prompts for loops and spelling correction
9386 Read-only variables.
9388 .Va Variable substitution
9390 When a suspended command is restarted, the shell prints the directory
9391 it started in if this is different from the current directory.
9393 be misleading (i.e., wrong) as the job may have changed directories internally.
9395 Shell builtin functions are not stoppable/restartable.
9399 are also not handled gracefully when stopping is
9403 , the shell will then immediately execute
9405 This is especially noticeable if this expansion results from an
9407 It suffices to place the sequence of commands in ()'s to force it
9408 to a subshell, i.e.,
9411 Control over tty output after processes are started is primitive; perhaps
9412 this will inspire someone to work on a good virtual terminal interface.
9413 In a virtual terminal interface much more interesting things could be
9414 done with output control.
9416 Alias substitution is most often used to clumsily simulate shell procedures;
9417 shell procedures should be provided rather than aliases.
9419 Control structures should be parsed rather than being recognized as
9421 This would allow control commands to be placed anywhere,
9424 , and to be used with
9431 doesn't ignore here documents when looking for its
9434 It should be possible to use the
9436 modifiers on the output of command
9439 The screen update for lines longer than the screen width is very poor
9440 if the terminal cannot move the cursor up (i.e., terminal type
9447 don't need to be environment variables.
9449 Glob-patterns which do not use
9459 are not negated correctly.
9461 The single-command form of
9463 does output redirection even if
9464 the expression is false and the command is not executed.
9466 \fIls\-F\fR includes file identification characters when sorting filenames
9467 and does not handle control characters in filenames well.
9471 Command substitution supports multiple commands and conditions, but not
9476 Report bugs at https://bugs.astron.com/, preferably with fixes.
9478 help maintain and test tcsh, add yourself to the mailing list in
9479 https://mailman.astron.com/.
9481 on a line by itself in the body.
9483 In 1964, DEC produced the PDP-6.
9484 The PDP-10 was a later re-implementation.
9486 was re-christened the DECsystem-10 in 1970 or so when DEC brought out the
9487 second model, the KI10.
9489 TENEX was created at Bolt, Beranek & Newman (a Cambridge, Massachusetts
9491 1972 as an experiment in demand-paged virtual memory operating systems.
9493 built a new pager for the DEC PDP-10 and created the OS to go with it.
9495 extremely successful in academia.
9497 In 1975, DEC brought out a new model of the PDP-10, the KL10; they intended to
9498 have only a version of TENEX, which they had licensed from BBN, for the new
9500 They called their version TOPS-20 (their capitalization is trademarked).
9501 A lot of TOPS-10 users (`The OPerating System for PDP-10') objected; thus DEC
9502 found themselves supporting two incompatible systems on the same hardware--but
9503 then there were 6 on the PDP-11!
9505 TENEX, and TOPS-20 to version 3, had command completion
9506 via a user-code-level subroutine library called ULTCMD.
9508 moved all that capability and more into the monitor (`kernel' for you Unix
9509 types), accessed by the COMND% JSYS (`Jump to SYStem' instruction, the
9510 supervisor call mechanism [are my IBM roots also showing?]).
9512 The creator of tcsh was impressed by this feature and several others of TENEX
9513 and TOPS-20, and created a version of csh which mimicked them.
9515 The system limits argument lists to ARG_MAX characters.
9517 The number of arguments to a command which involves filename expansion is
9518 limited to 1/6th the number of characters allowed in an argument list.
9520 Command substitutions may substitute no more characters than are allowed in
9523 To detect looping, the shell restricts the number of
9525 substitutions on a single line to 20.
9527 csh(1), emacs(1), ls(1), newgrp(1), sh(1), setpath(1), stty(1), su(1),
9528 tset(1), vi(1), x(1), access(2), execve(2), fork(2), killpg(2),
9529 pipe(2), setrlimit(2), sigvec(2), stat(2), umask(2), vfork(2), wait(2),
9530 malloc(3), setlocale(3), tty(4), a.out(5), termcap(5), environ(7),
9531 termio(7), Introduction to the C Shell
9533 This manual documents tcsh 6.22.03 (Astron) 2020-11-18.
9541 J.E. Kulp, IIASA, Laxenburg, Austria
9542 Job control and directory stack features
9544 Ken Greer, HP Labs, 1981
9545 File name completion
9547 Mike Ellis, Fairchild, 1983
9548 Command name recognition/completion
9550 Paul Placeway, Ohio State CIS Dept., 1983-1993
9551 Command line editor, prompt routines, new glob syntax and numerous fixes
9554 Karl Kleinpaste, CCI 1983-4
9555 Special aliases, directory stack extraction stuff, login/logout watch,
9556 scheduled events, and the idea of the new prompt format
9558 Rayan Zachariassen, University of Toronto, 1984
9561 builtins and numerous bug fixes, modifications
9564 Chris Kingsley, Caltech
9565 Fast storage allocator routines
9567 Chris Grevstad, TRW, 1987
9573 Christos S. Zoulas, Cornell U. EE Dept., 1987-94
9574 Ports to HPUX, SVR2 and SVR3, a SysV version of getwd.c, SHORT_STRINGS support
9575 and a new version of sh.glob.c
9577 James J Dempsey, BBN, and Paul Placeway, OSU, 1988
9580 Daniel Long, NNSC, 1988
9583 Patrick Wolfe, Kuck and Associates, Inc., 1988
9587 David C Lawrence, Rensselaer Polytechnic Institute, 1989
9589 and ambiguous completion listing
9591 Alec Wolman, DEC, 1989
9592 Newlines in the prompt
9594 Matt Landau, BBN, 1989
9597 Ray Moody, Purdue Physics, 1989
9598 Magic space bar history expansion
9600 Mordechai ????, Intel, 1989
9601 printprompt() fixes and additions
9603 Kazuhiro Honda, Dept. of Computer Science, Keio University, 1989
9604 Automatic spelling correction and
9607 Per Hedeland, Ellemtel, Sweden, 1990-
9608 Various bugfixes, improvements and manual updates
9610 Hans J. Albertsson (Sun Sweden)
9618 Interrupt handling fixes
9620 Michael Fine, Digital Equipment Corp
9621 Extended key support
9623 Eric Schnoebelen, Convex, 1990
9624 Convex support, lots of
9627 save and restore of directory stack
9629 Ron Flax, Apple, 1990
9632 Dan Oscarsson, LTH Sweden, 1990
9633 NLS support and simulated NLS support for non NLS sites, fixes
9635 Johan Widen, SICS Sweden, 1990
9641 Matt Day, Sanyo Icon, 1990
9642 POSIX termio support, SysV limit fixes
9644 Jaap Vermeulen, Sequent, 1990-91
9645 Vi mode fixes, expand-line, window change fixes, Symmetry port
9647 Martin Boyer, Institut de recherche d'Hydro-Quebec, 1991
9649 beeping options, modified the history search to search for
9650 the whole string from the beginning of the line to the cursor.
9652 Scott Krotz, Motorola, 1991
9655 David Dawes, Sydney U. Australia, Physics Dept., 1991
9656 SVR4 job control fixes
9658 Jose Sousa, Interactive Systems Corp., 1991
9665 Marc Horowitz, MIT, 1991
9666 ANSIfication fixes, new exec hashing code, imake fixes,
9669 Bruce Sterling Woodcock, sterling@netcom.com, 1991-1995
9670 ETA and Pyramid port, Makefile and lint fixes,
9673 various other portability changes and bug fixes
9676 .Va complete-word-fwd
9678 .Va complete-word-back
9680 Harry C. Pulley, 1992
9683 Andy Phillips, Mullard Space Science Lab U.K., 1992
9686 Beto Appleton, IBM Corp., 1992
9687 Walking process group fixes,
9690 POSIX file tests, POSIX SIGHUP
9692 Scott Bolte, Cray Computer Corp., 1992
9695 Kaveh R. Ghazi, Rutgers University, 1992
9696 Tek, m88k, Titan and Masscomp ports and fixes.
9697 Added autoconf support.
9699 Mark Linderman, Cornell University, 1992
9702 Mika Liljeberg, liljeber@kruuna.Helsinki.FI, 1992
9705 Tim P. Starrin, NASA Langley Research Center Operations, 1993
9708 Dave Schweisguth, Yale University, 1993-4
9709 New man page and tcsh.man2html
9711 Larry Schwimmer, Stanford University, 1993
9712 AFS and HESIOD patches
9714 Luke Mewburn, RMIT University, 1994-6
9715 Enhanced directory printing in prompt,
9721 Edward Hutchins, Silicon Graphics Inc., 1996
9724 Martin Kraemer, 1997
9725 Ported to Siemens Nixdorf EBCDIC machine
9727 Amol Deshpande, Microsoft, 1997
9728 Ported to WIN32 (Windows/95 and Windows/NT); wrote all the missing library
9729 and message catalog code to interface to Windows.
9736 Bryan Dunlap, Clayton Elwell, Karl Kleinpaste, Bob Manson, Steve Romig,
9737 Diana Smetters, Bob Sutterfield, Mark Verber, Elizabeth Zwicky and all
9738 the other people at Ohio State for suggestions and encouragement
9740 All the people on the net, for putting up with,
9741 reporting bugs in, and suggesting new additions to each and every version
9743 Richard M. Alderson III, for writing the
projects / freebsd.git / blob