1.\" 2.\" Copyright (c) 1980, 1990, 1993 3.\" The Regents of the University of California. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 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. 16.\" 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 27.\" SUCH DAMAGE. 28.\" 29.\" - Indent in multiples of 4, usually 8. 30.\" 31.\" - Use \` for literal back-quote (`). 32.\" 33.\" - Use \e for literal backslash (\). 34.\" 35.\" - Use \-, not -. 36.\" 37.\" - Include the tilde when naming dot files. .Pa ~/.login , not .Pa .login 38.\" 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). 42.\" 43.\" - Say `the shell', not `tcsh', unless distinguishing between tcsh and csh. 44.\" 45.\" - Say `shell variable'/`environment variable' instead of `variable' 46.\" and `builtin command'/`editor command' instead of `builtin' or `command' 47.\" unless the distinction is absolutely clear from context. 48.\" 49.\" - Use the simple present tense. `The shell uses', not `The shell will use'. 50.\" 51.\" - IMPORTANT: Cross-reference as much as possible. Commands, variables, 52.\" etc. in the reference section should be mentioned in the appropriate 53.\" descriptive section, or at least in the reference-section description 54.\" of another command (or whatever) which is mentioned in a description 55.\" section. Remember to note OS-specific things in "OS variant support", 56.\" new features in NEW FEATURES and referenced external commands in SEE 57.\" ALSO. 58.\" 59.\" UPDATE NEXT LINE FOR RELEASE 60.Dd November 24, 2022 61.Dt TCSH 1 62.\" UPDATE NEXT LINE FOR RELEASE 63.Os Astron 6.24.02 64. 65.Sh NAME 66.Nm tcsh 67.Nd C shell with file name completion and command line editing 68. 69.Sh SYNOPSIS 70.Nm 71.Op Fl bcdefFimnqstvVxX 72.Op Fl D Ns Ar name Ns Op Ns = Ns Ar value 73.Op Ar arg 74\&... 75.Nm 76.Fl l 77. 78.Sh DESCRIPTION 79.Nm 80is an enhanced but completely compatible version of the Berkeley 81UNIX C shell, 82.Xr csh 1 . 83It is a command language interpreter usable both as an interactive login 84shell and a shell script command processor. 85It includes a command-line editor (see 86.Sx The command-line editor ) , 87programmable word completion (see 88.Sx Completion and listing ) , 89spelling correction (see 90.Sx Spelling correction ) , 91a history mechanism (see 92.Sx History substitution ) , 93job control (see 94.Sx Jobs ) 95and a C-like syntax. 96The 97.Sx NEW FEATURES 98section describes major enhancements of 99.Nm 100over 101.Xr csh 1 . 102Throughout this manual, features of 103.Nm 104not found in most 105.Xr csh 1 106implementations 107(specifically, the 4.4BSD 108.Xr csh 1 ) 109are labeled with 110.Sq (+) , 111and features which are present in 112.Xr csh 1 113but not usually documented are labeled with 114.Sq (u) . 115. 116.Ss Argument list processing 117If the first argument (argument 0) to the shell is 118.Ql \- 119then it is a login shell. 120A login shell can be also specified by invoking the shell with 121the 122.Fl l 123flag as the only argument. 124.Pp 125The rest of the flag arguments are interpreted as follows: 126.Bl -tag -width indent 127. 128.It Fl b 129Forces a 130.Dq break 131from option processing, causing any 132further shell arguments to be treated as non-option arguments. 133The remaining arguments will not be interpreted as shell options. 134This may be used to pass options to a shell script without confusion 135or possible subterfuge. 136The shell will not run a set-user ID script without this option. 137. 138.It Fl c 139Commands are read from the following argument (which must be present, and 140must be a single argument), 141stored in the 142.Ic command 143shell variable for reference, and executed. 144Any remaining arguments are placed in the 145.Ic argv 146shell variable. 147. 148.It Fl d 149The shell loads the directory stack from 150.Pa ~/.cshdirs 151as described under 152.Sx Startup and shutdown , 153whether or not it is a login shell. (+) 154. 155.It Fl D Ns Ar name Ns Op Ns = Ns Ar value 156Sets the environment variable 157.Ar name 158to 159.Ar value . 160(Domain/OS only) (+) 161. 162.It Fl e 163The shell exits if any invoked command terminates abnormally or 164yields a non-zero exit status. 165. 166.It Fl f 167The shell does not load any resource or startup files, or perform any 168command hashing, and thus starts faster. 169. 170.It Fl F 171The shell uses 172.Xr fork 2 173instead of 174.Xr vfork 2 175to spawn processes. (+) 176. 177.It Fl i 178The shell is interactive and prompts for its top-level input, even if 179it appears to not be a terminal. 180Shells are interactive without this option if 181their inputs and outputs are terminals. 182. 183.It Fl l 184The shell is a login shell. 185Applicable only if 186.Fl l 187is the only 188flag specified. 189. 190.It Fl m 191The shell loads 192.Pa ~/.tcshrc 193even if it does not belong to the effective user. 194Newer versions of 195.Xr su 1 196can pass 197.Fl m 198to the shell. (+) 199. 200.It Fl n 201The shell parses commands but does not execute them. 202This aids in debugging shell scripts. 203. 204.It Fl q 205The shell accepts SIGQUIT (see 206.Sx Signal handling ) 207and behaves when it is used under a debugger. 208Job control is disabled. (u) 209. 210.It Fl s 211Command input is taken from the standard input. 212. 213.It Fl t 214The shell reads and executes a single line of input. 215A 216.Ql \e 217may be used to 218escape the newline at the end of this line and continue onto another line. 219. 220.It Fl v 221Sets the 222.Ic verbose 223shell variable, so that 224command input is echoed after history substitution. 225. 226.It Fl x 227Sets the 228.Ic echo 229shell variable, so that commands are echoed 230immediately before execution. 231. 232.It Fl V 233Sets the 234.Ic verbose 235shell variable even before executing 236.Pa ~/.tcshrc . 237. 238.It Fl X 239Is to 240.Fl x 241as 242.Fl V 243is to 244.Fl v . 245. 246.It Fl \-help 247Print a help message on the standard output and exit. (+) 248. 249.It Fl \-version 250Print the version/platform/compilation options on the standard output and exit. 251This information is also contained in the 252.Ic version 253shell variable. (+) 254.El 255.Pp 256After processing of flag arguments, if arguments remain but none of the 257.Fl c , 258.Fl i , 259.Fl s , 260or 261.Fl t 262options were given, the first argument is taken as the name of a file of 263commands, or 264.Dq script , 265to be executed. 266The shell opens this file and saves its name for possible 267resubstitution by 268.Ql $0 . 269Because many systems use either the standard 270version 6 or version 7 shells whose shell scripts are not compatible 271with this shell, the shell uses such a 272.Dq standard 273shell to execute a script 274whose first character is not a 275.Ql # , 276i.e., that does not start with a 277comment. 278.Pp 279Remaining arguments are placed in the 280.Ic argv 281shell variable. 282. 283.Ss Startup and shutdown 284A login shell begins by executing commands from the system files 285.Pa /etc/csh.cshrc 286and 287.Pa /etc/csh.login . 288It then executes commands from files in the user's 289.Pa home 290directory: 291first 292.Pa ~/.tcshrc (+) 293or, if 294.Pa ~/.tcshrc 295is not found, 296.Pa ~/.cshrc , 297then the contents of 298.Pa ~/.history 299(or the value of the 300.Ic histfile 301shell variable) are loaded into memory, then 302.Pa ~/.login , 303and finally 304.Pa ~/.cshdirs 305(or the value of the 306.Ic dirsfile 307shell variable) (+). 308The shell may read 309.Pa /etc/csh.login 310before instead of after 311.Pa /etc/csh.cshrc , 312and 313.Pa ~/.login 314before instead of after 315.Pa ~/.tcshrc 316or 317.Pa ~/.cshrc 318and 319.Pa ~/.history , 320if so compiled; 321see the 322.Ic version 323shell variable. (+) 324.Pp 325Non-login shells read only 326.Pa /etc/csh.cshrc 327and 328.Pa ~/.tcshrc 329or 330.Pa ~/.cshrc 331on startup. 332.Pp 333For examples of startup files, please consult: 334.Lk http://tcshrc.sourceforge.net 335.Pp 336Commands like 337.Xr stty 1 338and 339.Xr tset 1 , 340which need be run only once per login, usually go in one's 341.Pa ~/.login 342file. 343Users who need to use the same set of files with both 344.Xr csh 1 345and 346.Nm 347can have only a 348.Pa ~/.cshrc 349which checks for the existence of the 350.Ic tcsh 351shell variable (q.v.) before using 352.Nm Ns 353\-specific commands, 354or can have both a 355.Pa ~/.cshrc 356and a 357.Pa ~/.tcshrc 358which 359.Ic source Ns 360s 361(see the builtin command) 362.Pa ~/.cshrc . 363The rest of this manual uses 364.Pa ~/.tcshrc 365to mean 366.Pa ~/.tcshrc 367or, 368if 369.Pa ~/.tcshrc 370is not found, 371.Pa ~/.cshrc . 372.Pp 373In the normal case, the shell begins reading commands from the terminal, 374prompting with 375.Sq Li >\ \& . 376(Processing of arguments and the use of the shell to 377process files containing command scripts are described later.) 378The shell repeatedly reads a line of command input, breaks it into words, 379places it on the command history list, parses it and executes each command 380in the line. 381.Pp 382One can log out by typing 383.Sq ^D 384on an empty line, 385.Ic logout 386or 387.Ic login 388or 389via the shell's autologout mechanism (see the 390.Ic autologout 391shell variable). 392When a login shell terminates it sets the 393.Ic logout 394shell variable to 395.Ql normal 396or 397.Ql automatic 398as appropriate, then executes commands from the files 399.Pa /etc/csh.logout 400and 401.Pa ~/.logout . 402The shell may drop DTR on logout 403if so compiled; see the 404.Ic version 405shell variable. 406.Pp 407The names of the system login and logout files vary from system to system for 408compatibility with different 409.Xr csh 1 410variants; see 411.Sx FILES . 412. 413.Ss Editing 414We first describe 415.Sx The command-line editor . 416The 417.Sx Completion and listing 418and 419.Sx Spelling correction 420sections describe two sets of functionality that are implemented as editor 421commands but which deserve their own treatment. 422Finally, 423.Sx Editor commands 424lists and describes 425the editor commands specific to the shell and their default bindings. 426. 427.Ss The command-line editor (+) 428Command-line input can be edited using key sequences much like those used in 429.Xr emacs 1 430or 431.Xr vi 1 . 432The editor is active only when the 433.Ic edit 434shell variable is set, which it is by default in interactive shells. 435The 436.Ic bindkey 437builtin can display and change key bindings. 438.Xr emacs 1 Ns 439\-style key bindings are used by default 440(unless the shell was compiled otherwise; see the 441.Ic version 442shell variable), 443but 444.Ic bindkey 445can change the key bindings to 446.Xr vi 1 Ns 447\-style bindings en masse. 448.Pp 449The shell always binds the arrow keys (as defined in the 450.Ev TERMCAP 451environment variable) to: 452.Pp 453.Bl -tag -width right -offset indent -compact 454.It down 455.Ic down-history 456.It up 457.Ic up-history 458.It left 459.Ic backward-char 460.It right 461.Ic forward-char 462.El 463.Pp 464unless doing so would alter another single-character binding. 465One can set the arrow key escape sequences to the empty string with 466.Ic settc 467to prevent these bindings. 468The ANSI/VT100 sequences for arrow keys are always bound. 469.Pp 470Other key bindings are, for the most part, what 471.Xr emacs 1 472and 473.Xr vi 1 474users would expect and can easily be displayed by 475.Ic bindkey , 476so there 477is no need to list them here. 478Likewise, 479.Ic bindkey 480can list the editor 481commands with a short description of each. 482Certain key bindings have different behavior depending if 483.Xr emacs 1 484or 485.Xr vi 1 Ns 486\-style bindings are being used; see 487.Ic vimode 488for more information. 489.Pp 490Note that editor commands do not have the same notion of a 491.Dq word 492as does the shell. 493The editor delimits words with any non-alphanumeric characters not in 494the shell variable 495.Ic wordchars , 496while the shell recognizes only whitespace 497and some of the characters with special meanings to it, listed under 498.Sx Lexical structure . 499. 500.Ss Completion and listing (+) 501The shell is often able to complete words when given a unique abbreviation. 502Type part of a word (for example 503.Ql ls /usr/lost ) 504and hit the tab key to run the 505.Ic complete-word 506editor command. 507The shell completes the filename 508.Pa /usr/lost 509to 510.Pa /usr/lost+found/ , 511replacing the incomplete word with the complete word in the input buffer. 512(Note the terminal 513.Sq Pa / ; 514completion adds a 515.Ql / 516to the end of completed directories and a space to the end of other completed 517words, to speed typing and provide a visual indicator of successful completion. 518The 519.Ic addsuffix 520shell variable can be unset to prevent this.) 521If no match is found (perhaps 522.Pa /usr/lost+found 523doesn't exist), the terminal bell rings. 524If the word is already complete (perhaps there is a 525.Pa /usr/lost 526on your 527system, or perhaps you were thinking too far ahead and typed the whole thing) 528a 529.Ql / 530or space is added to the end if it isn't already there. 531.Pp 532Completion works anywhere in the line, not at just the end; completed 533text pushes the rest of the line to the right. 534Completion in the middle of a word 535often results in leftover characters to the right of the cursor that need 536to be deleted. 537.Pp 538Commands and variables can be completed in much the same way. 539For example, typing 540.Ql em[tab] 541would complete 542.Ql em 543to 544.Ql emacs 545if 546.Ql emacs 547were the only command on your system beginning with 548.Ql em . 549Completion can find a command in any directory in 550.Ic path 551or if given a full pathname. 552Typing 553.Ql echo $ar[tab] 554would complete 555.Ql $ar 556to 557.Ql $argv 558if no other variable began with 559.Ql ar . 560.Pp 561The shell parses the input buffer to determine whether the word you want to 562complete should be completed as a filename, command or variable. 563The first word in the buffer and the first word following 564.Ql \&; , 565.Ql | , 566.Ql |& , 567.Ql && , 568or 569.Ql || 570is considered to be a command. 571A word beginning with 572.Ql $ 573is considered to be a variable. 574Anything else is a filename. 575An empty line is 576.Dq completed 577as a filename. 578.Pp 579You can list the possible completions of a word at any time by typing 580.Sq ^D 581to run the 582.Ic delete-char-or-list-or-eof 583editor command. 584The shell lists the possible completions using the 585.Ic ls\-F 586builtin (q.v.) 587and reprints the prompt and unfinished command line, for example: 588.Bd -literal -offset indent 589> ls /usr/l[^D] 590lbin/ lib/ local/ lost+found/ 591> ls /usr/l 592.Ed 593.Pp 594If the 595.Ic autolist 596shell variable is set, the shell lists the remaining 597choices (if any) whenever completion fails: 598.Bd -literal -offset indent 599> set autolist 600> nm /usr/lib/libt[tab] 601libtermcap.a@ libtermlib.a@ 602> nm /usr/lib/libterm 603.Ed 604.Pp 605If the 606.Ic autolist 607shell variable is set to 608.Ql ambiguous , 609choices are listed only when 610completion fails and adds no new characters to the word being completed. 611.Pp 612A filename to be completed can contain variables, your own or others' home 613directories abbreviated with 614.Ql ~ 615(see 616.Sx Filename substitution ) 617and directory stack entries abbreviated with 618.Ql = 619(see 620.Sx Directory stack substitution ) . 621For example, 622.Bd -literal -offset indent 623> ls ~k[^D] 624kahn kas kellogg 625> ls ~ke[tab] 626> ls ~kellogg/ 627.Ed 628.Pp 629or 630.Bd -literal -offset indent 631> set local = /usr/local 632> ls $lo[tab] 633> ls $local/[^D] 634bin/ etc/ lib/ man/ src/ 635> ls $local/ 636.Ed 637.Pp 638Note that variables can also be expanded explicitly with the 639.Ic expand-variables 640editor command. 641.Pp 642.Ic delete-char-or-list-or-eof 643lists at only the end of the line; 644in the middle of a line it deletes the character under the cursor and 645on an empty line it logs one out or, if the 646.Ic ignoreeof 647variable is set, does nothing. 648.Sq M-^D , 649bound to the editor command 650.Ic list-choices , 651lists completion 652possibilities anywhere on a line, and 653.Ic list-choices 654(or any one of the 655related editor commands that do or don't delete, list and/or log out, 656listed under 657.Ic delete-char-or-list-or-eof ) 658can be bound to 659.Sq ^D 660with the 661.Ic bindkey 662builtin command if so desired. 663.Pp 664The 665.Ic complete-word-fwd 666and 667.Ic complete-word-back 668editor commands 669(not bound to any keys by default) can be used to cycle up and down through 670the list of possible completions, replacing the current word with the next or 671previous word in the list. 672.Pp 673The shell variable 674.Ic fignore 675can be set to a list of suffixes to be ignored by completion. 676Consider the following: 677.Bd -literal -offset indent 678> ls 679Makefile condiments.h~ main.o side.c 680README main.c meal side.o 681condiments.h main.c~ 682> set fignore = (.o \e~) 683> emacs ma[^D] 684main.c main.c~ main.o 685> emacs ma[tab] 686> emacs main.c 687.Ed 688.Pp 689.Ql main.c~ 690and 691.Ql main.o 692are ignored by completion (but not listing), 693because they end in suffixes in 694.Ic fignore . 695Note that a 696.Ql \e 697was needed in front of 698.Ql ~ 699to prevent it from being expanded to 700.Ic home 701as described under 702.Sx Filename substitution . 703.Ic fignore 704is ignored if only one completion is possible. 705.Pp 706If the 707.Ic complete 708shell variable is set to 709.Ql enhance , 710completion 1) ignores case and 2) considers periods, hyphens and underscores 711.Po 712.Ql \&. , 713.Ql \- , 714and 715.Ql _ 716.Pc 717to be word separators and hyphens and underscores to be equivalent. 718If you had the following files 719.Bd -literal -offset indent 720comp.lang.c comp.lang.perl comp.std.c++ 721comp.lang.c++ comp.std.c 722.Ed 723.Pp 724and typed 725.Ql mail \-f c.l.c[tab] , 726it would be completed to 727.Ql mail \-f comp.lang.c , 728and 729.Sq ^D 730would list 731.Ql comp.lang.c 732and 733.Ql comp.lang.c++ . 734.Ql mail \-f c..c++[^D] 735would list 736.Ql comp.lang.c++ 737and 738.Ql comp.std.c++ . 739Typing 740.Ql rm a\-\-file[^D] 741in the following directory 742.Bd -literal -offset indent 743A_silly_file a-hyphenated-file another_silly_file 744.Ed 745.Pp 746would list all three files, because case is ignored and hyphens and 747underscores are equivalent. 748Periods, however, are not equivalent to 749hyphens or underscores. 750.Pp 751If the 752.Ic complete 753shell variable is set to 754.Ql Enhance , 755completion 756ignores case and differences between a hyphen and an underscore word 757separator only when the user types a lowercase character or a hyphen. 758Entering an uppercase character or an underscore will not match the 759corresponding lowercase character or hyphen word separator. 760Typing 761.Ql rm a\-\-file[^D] 762in the directory of the previous example would 763still list all three files, but typing 764.Ql rm A\-\-file 765would match only 766.Ql A_silly_file 767and typing 768.Ql rm a__file[^D] 769would match just 770.Ql A_silly_file 771and 772.Ql another_silly_file 773because the user explicitly used an uppercase 774or an underscore character. 775.Pp 776Completion and listing are affected by several other shell variables: 777.Ic recexact 778can be set to complete on the shortest possible unique 779match, even if more typing might result in a longer match: 780.Bd -literal -offset indent 781> ls 782fodder foo food foonly 783> set recexact 784> rm fo[tab] 785.Ed 786.Pp 787just beeps, because 788.Ql fo 789could expand to 790.Ql fod 791or 792.Ql foo , 793but if we type another 794.Ql o , 795.Bd -literal -offset indent 796> rm foo[tab] 797> rm foo 798.Ed 799.Pp 800the completion completes on 801.Ql foo , 802even though 803.Ql food 804and 805.Ql foonly 806also match. 807.Ic autoexpand 808can be set to run the 809.Ic expand-history 810editor command 811before each completion attempt, 812.Ic autocorrect 813can be set to 814spelling-correct the word to be completed (see 815.Sx Spelling correction ) 816before each completion attempt and 817.Ic correct 818can be set to complete commands automatically after one hits 819return. 820.Ic matchbeep 821can be set to make completion beep or not beep in a variety 822of situations, and 823.Ic nobeep 824can be set to never beep at all. 825.Ic nostat 826can be set to a list of directories and/or patterns that 827match directories to prevent the completion mechanism from 828.Xr stat 2 Ns 829ing 830those directories. 831.Ic listmax 832and 833.Ic listmaxrows 834can be set to limit the number of items 835and rows (respectively) that are listed without asking first. 836.Ic recognize_only_executables 837can be set to make the shell list only 838executables when listing commands, but it is quite slow. 839.Pp 840Finally, the 841.Ic complete 842builtin command can be used to tell the shell how 843to complete words other than filenames, commands and variables. 844Completion and listing do not work on glob-patterns (see 845.Sx Filename substitution ) , 846but the 847.Ic list-glob 848and 849.Ic expand-glob 850editor commands perform 851equivalent functions for glob-patterns. 852. 853.Ss Spelling correction (+) 854The shell can sometimes correct the spelling of filenames, commands and 855variable names as well as completing and listing them. 856.Pp 857Individual words can be spelling-corrected with the 858.Ic spell-word 859editor command (usually bound to 860.Sq M-s 861and 862.Sq M-S ) 863and the entire input buffer with 864.Ic spell-line 865(usually bound to 866.Sq M-$ ) . 867The 868.Ic correct 869shell variable can be set to 870.Ql cmd 871to correct the command name or 872.Ql all 873to correct the entire line each time return is typed, and 874.Ic autocorrect 875can be set to correct the word to be completed 876before each completion attempt. 877.Pp 878When spelling correction is invoked in any of these ways and 879the shell thinks that any part of the command line is misspelled, 880it prompts with the corrected line: 881.Bd -literal -offset indent 882> set correct = cmd 883> lz /usr/bin 884CORRECT>ls /usr/bin (y|n|e|a)? 885.Ed 886.Pp 887One can answer 888.Ql y 889or space to execute the corrected line, 890.Ql e 891to leave the uncorrected command in the input buffer, 892.Ql a 893to abort the command as if 894.Sq ^C 895had been hit, and 896anything else to execute the original line unchanged. 897.Pp 898Spelling correction recognizes user-defined completions (see the 899.Ic complete 900builtin command). 901If an input word in a position for 902which a completion is defined resembles a word in the completion list, 903spelling correction registers a misspelling and suggests the latter 904word as a correction. 905However, if the input word does not match any of 906the possible completions for that position, spelling correction does 907not register a misspelling. 908.Pp 909Like completion, spelling correction works anywhere in the line, 910pushing the rest of the line to the right and possibly leaving 911extra characters to the right of the cursor. 912. 913.Ss Editor commands (+) 914.Ic bindkey 915lists key bindings and 916.Ic bindkey \-l 917lists and briefly describes editor commands. 918Only new or especially interesting editor commands are described here. 919See 920.Xr emacs 1 921and 922.Xr vi 1 923for descriptions of each editor's key bindings. 924.Pp 925The character or characters to which each command is bound by default is 926given in parentheses. 927.Sq ^ Ns Ar character 928means a control character and 929.Sq M- Ns Ar character 930a meta character, typed as 931.Sq escape- Ns Ar character 932on terminals without a meta key. 933Case counts, but commands that are bound 934to letters by default are bound to both lower- and uppercase letters for 935convenience. 936.Pp 937Supported editor commands are: 938.Bl -tag -width indent 939. 940.It Ic backward-char No (^B, left) 941Move back a character. 942Cursor behavior modified by 943.Ic vimode . 944. 945.It Ic backward-delete-word No (M-^H, M-^?) 946Cut from beginning of current word to cursor - saved in cut buffer. 947Word boundary behavior modified by 948.Ic vimode . 949. 950.It Ic backward-word No (M-b, M-B) 951Move to beginning of current word. 952Word boundary and cursor behavior modified by 953.Ic vimode . 954. 955.It Ic beginning-of-line No (^A, home) 956Move to beginning of line. 957Cursor behavior modified by 958.Ic vimode . 959. 960.It Ic capitalize-word No (M-c, M-C) 961Capitalize the characters from cursor to end of current word. 962Word boundary behavior modified by 963.Ic vimode . 964. 965.It Ic complete-word No (tab) 966Completes a word as described under 967.Sx Completion and listing . 968. 969.It Ic complete-word-back No (not bound) 970Like 971.Ic complete-word-fwd , 972but steps up from the end of the list. 973. 974.It Ic complete-word-fwd No (not bound) 975Replaces the current word with the first word in the list of possible 976completions. 977May be repeated to step down through the list. 978At the end of the list, beeps and reverts to the incomplete word. 979. 980.It Ic complete-word-raw No (^X-tab) 981Like 982.Ic complete-word , 983but ignores user-defined completions. 984. 985.It Ic copy-prev-word No (M-^_) 986Copies the previous word in the current line into the input buffer. 987See also 988.Ic insert-last-word . 989Word boundary behavior modified by 990.Ic vimode . 991. 992.It Ic dabbrev-expand No (M-/) 993Expands the current word to the most recent preceding one for which 994the current is a leading substring, wrapping around the history list 995(once) if necessary. 996Repeating 997.Ic dabbrev-expand 998without any intervening typing 999changes to the next previous word etc., skipping identical matches 1000much like 1001.Ic history-search-backward 1002does. 1003. 1004.It Ic delete-char No (not bound) 1005Deletes the character under the cursor. 1006See also 1007.Ic delete-char-or-list-or-eof . 1008Cursor behavior modified by 1009.Ic vimode . 1010. 1011.It Ic delete-char-or-eof No (not bound) 1012Does 1013.Ic delete-char 1014if there is a character under the cursor or 1015.Ic end-of-file 1016on an empty line. 1017See also 1018.Ic delete-char-or-list-or-eof . 1019Cursor behavior modified by 1020.Ic vimode . 1021. 1022.It Ic delete-char-or-list No (not bound) 1023Does 1024.Ic delete-char 1025if there is a character under the cursor 1026or 1027.Ic list-choices 1028at the end of the line. 1029See also 1030.Ic delete-char-or-list-or-eof . 1031. 1032.It Ic delete-char-or-list-or-eof No (^D) 1033Does 1034.Ic delete-char 1035if there is a character under the cursor, 1036.Ic list-choices 1037at the end of the line or 1038.Ic end-of-file 1039on an empty line. 1040See also those three commands, each of which does only a single action, and 1041.Ic delete-char-or-eof , 1042.Ic delete-char-or-list , 1043and 1044.Ic list-or-eof , 1045each of which does a different two out of the three. 1046. 1047.It Ic delete-word No (M-d, M-D) 1048Cut from cursor to end of current word - save in cut buffer. 1049Word boundary behavior modified by 1050.Ic vimode . 1051. 1052.It Ic down-history No (down-arrow, ^N) 1053Like 1054.Ic up-history , 1055but steps down, stopping at the original input line. 1056. 1057.It Ic downcase-word No (M-l, M-L) 1058Lowercase the characters from cursor to end of current word. 1059Word boundary behavior modified by 1060.Ic vimode . 1061. 1062.It Ic end-of-file No (not bound) 1063Signals an end of file, causing the shell to exit unless the 1064.Ic ignoreeof 1065shell variable (q.v.) is set to prevent this. 1066See also 1067.Ic delete-char-or-list-or-eof . 1068. 1069.It Ic end-of-line No (^E, end) 1070Move cursor to end of line. 1071Cursor behavior modified by 1072.Ic vimode . 1073. 1074.It Ic expand-history No (M-space) 1075Expands history substitutions in the current word. 1076See 1077.Sx History substitution . 1078See also 1079.Ic magic-space , 1080.Ic toggle-literal-history , 1081and the 1082.Ic autoexpand 1083shell variable. 1084. 1085.It Ic expand-glob No (^X-*) 1086Expands the glob-pattern to the left of the cursor. 1087See 1088.Sx Filename substitution . 1089. 1090.It Ic expand-line No (not bound) 1091Like 1092.Ic expand-history , 1093but expands history substitutions in each word in the input buffer. 1094. 1095.It Ic expand-variables No (^X-$) 1096Expands the variable to the left of the cursor. 1097See 1098.Sx Variable substitution . 1099. 1100.It Ic forward-char No (^F, right) 1101Move forward one character. 1102Cursor behavior modified by 1103.Ic vimode . 1104. 1105.It Ic forward-word No (M-f, M-F) 1106Move forward to end of current word. 1107Word boundary and cursor behavior modified by 1108.Ic vimode . 1109. 1110.It Ic history-search-backward No (M-p, M-P) 1111Searches backwards through the history list for a command beginning with 1112the current contents of the input buffer up to the cursor and copies it 1113into the input buffer. 1114The search string may be a glob-pattern (see 1115.Sx Filename substitution ) 1116containing 1117.Ql * , 1118.Ql \&? , 1119.Ql [] , 1120or 1121.Ql {} . 1122.Ic up-history 1123and 1124.Ic down-history 1125will proceed from the 1126appropriate point in the history list. 1127Emacs mode only. 1128See also 1129.Ic history-search-forward 1130and 1131.Ic i-search-back . 1132. 1133.It Ic history-search-forward No (M-n, M-N) 1134Like 1135.Ic history-search-backward , 1136but searches forward. 1137. 1138.It Ic i-search-back No (not bound) 1139Searches backward like 1140.Ic history-search-backward , 1141copies the first match 1142into the input buffer with the cursor positioned at the end of the pattern, 1143and prompts with 1144.Sq Li bck:\ \& 1145and the first match. 1146Additional characters may be 1147typed to extend the search, 1148.Ic i-search-back 1149may be typed to continue 1150searching with the same pattern, wrapping around the history list if 1151necessary, 1152.Ic ( i-search-back 1153must be bound to a 1154single character for this to work) or one of the following special characters 1155may be typed: 1156.Pp 1157.Bl -tag -width indent -compact 1158.It ^W 1159Appends the rest of the word under the cursor to the search pattern. 1160.It delete 1161(or any character bound to 1162.Ic backward-delete-char ) 1163Undoes the effect of the last character typed and deletes a character 1164from the search pattern if appropriate. 1165.It ^G 1166If the previous search was successful, aborts the entire search. 1167If not, goes back to the last successful search. 1168.It escape 1169Ends the search, leaving the current line in the input buffer. 1170.El 1171.Pp 1172Any other character not bound to 1173.Ic self-insert-command 1174terminates the 1175search, leaving the current line in the input buffer, and 1176is then interpreted as normal input. 1177In particular, a carriage return 1178causes the current line to be executed. 1179See also 1180.Ic i-search-fwd 1181and 1182.Ic history-search-backward . 1183Word boundary behavior modified by 1184.Ic vimode . 1185. 1186.It Ic i-search-fwd No (not bound) 1187Like 1188.Ic i-search-back , 1189but searches forward. 1190Word boundary behavior modified by 1191.Ic vimode . 1192. 1193.It Ic insert-last-word No (M-_) 1194Inserts the last word of the previous input line 1195.Pq Ql \&!$ 1196into the input buffer. 1197See also 1198.Ic copy-prev-word . 1199. 1200.It Ic list-choices No (M-^D) 1201Lists completion possibilities as described under 1202.Sx Completion and listing . 1203See also 1204.Ic delete-char-or-list-or-eof 1205and 1206.Ic list-choices-raw . 1207. 1208.It Ic list-choices-raw No (^X-^D) 1209Like 1210.Ic list-choices , 1211but ignores user-defined completions. 1212. 1213.It Ic list-glob No (^X-g, ^X-G) 1214Lists (via the 1215.Ic ls\-F 1216builtin) matches to the glob-pattern 1217(see 1218.Sx Filename substitution ) 1219to the left of the cursor. 1220. 1221.It Ic list-or-eof No (not bound) 1222Does 1223.Ic list-choices 1224or 1225.Ic end-of-file 1226on an empty line. 1227See also 1228.Ic delete-char-or-list-or-eof . 1229. 1230.It Ic magic-space No (not bound) 1231Expands history substitutions in the current line, 1232like 1233.Ic expand-history , 1234and inserts a space. 1235.Ic magic-space 1236is designed to be bound to the space bar, 1237but is not bound by default. 1238. 1239.It Ic normalize-command No (^X-?) 1240Searches for the current word in 1241.Ev PATH 1242and, if it is found, replaces it with 1243the full path to the executable. 1244Special characters are quoted. 1245Aliases are 1246expanded and quoted but commands within aliases are not. 1247This command is 1248useful with commands that take commands as arguments, e.g., 1249.Ql dbx 1250and 1251.Ql sh \-x . 1252. 1253.It Ic normalize-path No (^X-n, ^X-N) 1254Expands the current word as described under the 1255.Ql expand 1256setting 1257of the 1258.Ic symlinks 1259shell variable. 1260. 1261.It Ic overwrite-mode No (unbound) 1262Toggles between input and overwrite modes. 1263. 1264.It Ic run-fg-editor No (M-^Z) 1265Saves the current input line and 1266looks for a stopped job where the file name portion of its first word 1267is found in the 1268.Ic editors 1269shell variable. 1270If 1271.Ic editors 1272is not set, then the file name portion of the 1273.Ev EDITOR 1274environment variable 1275.Ql ( ed 1276if unset) 1277and the 1278.Ev VISUAL 1279environment variable 1280.Ql ( vi 1281if unset) 1282will be used. 1283If such a job is found, it is restarted as if 1284.Ql fg % Ns Ar job 1285had been typed. 1286This is used to toggle back and forth between an editor and 1287the shell easily. 1288Some people bind this command to 1289.Sq ^Z 1290so they 1291can do this even more easily. 1292. 1293.It Ic run-help No (M-h, M-H) 1294Searches for documentation on the current command, using the same notion of 1295.Dq current command 1296as the completion routines, and prints it. 1297There is no way 1298to use a pager; 1299.Ic run-help 1300is designed for short help files. 1301If the special alias 1302.Ic helpcommand 1303is defined, it is run with the 1304command name as a sole argument. 1305Else, 1306documentation should be in a file named 1307.Pa command.help , 1308.Pa command.1 , 1309.Pa command.6 , 1310.Pa command.8 , 1311or 1312.Pa command , 1313which should be in one 1314of the directories listed in the 1315.Ev HPATH 1316environment variable. 1317If there is more than one help file only the first is printed. 1318. 1319.It Ic self-insert-command No (text characters) 1320In insert mode (the default), inserts the typed character into 1321the input line after the character under the cursor. 1322In overwrite mode, replaces the character under the cursor with the typed character. 1323The input mode is normally preserved between lines, but the 1324.Ic inputmode 1325shell variable can be set to 1326.Ql insert 1327or 1328.Ql overwrite 1329to put the 1330editor in that mode at the beginning of each line. 1331See also 1332.Ic overwrite-mode . 1333. 1334.It Ic sequence-lead-in No (arrow prefix, meta prefix, ^X) 1335Indicates that the following characters are part of a 1336multi-key sequence. 1337Binding a command to a multi-key sequence really creates 1338two bindings: the first character to 1339.Ic sequence-lead-in 1340and the 1341whole sequence to the command. 1342All sequences beginning with a character 1343bound to 1344.Ic sequence-lead-in 1345are effectively bound to 1346.Ic undefined-key 1347unless bound to another command. 1348. 1349.It Ic spell-line No (M-$) 1350Attempts to correct the spelling of each word in the input buffer, like 1351.Ic spell-word , 1352but ignores words whose first character is one of 1353.Ql \- , 1354.Ql \&! , 1355.Ql ^ , 1356or 1357.Ql % , 1358or which contain 1359.Ql \e , 1360.Ql * , 1361or 1362.Ql \&? , 1363to avoid problems with switches, substitutions and the like. 1364See 1365.Sx Spelling correction . 1366. 1367.It Ic spell-word No (M-s, M-S) 1368Attempts to correct the spelling of the current word as described under 1369.Sx Spelling correction . 1370Checks each component of a word which appears to be a pathname. 1371. 1372.It Ic toggle-literal-history No (M-r, M-R) 1373Expands or 1374unexpands 1375history substitutions in the input buffer. 1376See also 1377.Ic expand-history 1378and the 1379.Ic autoexpand 1380shell variable. 1381. 1382.It Ic undefined-key No (any unbound key) 1383Beeps. 1384. 1385.It Ic up-history No (up-arrow, ^P) 1386Copies the previous entry in the history list into the input buffer. 1387If 1388.Ic histlit 1389is set, uses the literal form of the entry. 1390May be repeated to step up through the history list, stopping at the top. 1391. 1392.It Ic upcase-word No (M-u, M-U) 1393Uppercase the characters from cursor to end of current word. 1394Word boundary behavior modified by 1395.Ic vimode . 1396. 1397.It Ic vi-beginning-of-next-word No (not bound) 1398Vi goto the beginning of next word. 1399Word boundary and cursor behavior modified by 1400.Ic vimode . 1401. 1402.It Ic vi-eword No (not bound) 1403Vi move to the end of the current word. 1404Word boundary behavior modified by 1405.Ic vimode . 1406. 1407.It Ic vi-search-back No (?) 1408Prompts with 1409.Sq Li \&? 1410for a search string (which may be a glob-pattern, as with 1411.Ic history-search-backward ) , 1412searches for it and copies it into the input buffer. 1413The bell rings if no match is found. 1414Hitting return ends the search and leaves the last match in the input 1415buffer. 1416Hitting escape ends the search and executes the match. 1417.Ic vi 1418mode only. 1419. 1420.It Ic vi-search-fwd No (/) 1421Like 1422.Ic vi-search-back , 1423but searches forward. 1424. 1425.It Ic which-command No (M-?) 1426Does a 1427.Ic which 1428(see the description of the builtin command) on the 1429first word of the input buffer. 1430. 1431.It Ic yank-pop No (M-y) 1432When executed immediately after a 1433.Ic yank 1434or another 1435.Ic yank-pop , 1436replaces the yanked string with the next previous string from the 1437killring. This also has the effect of rotating the killring, such that 1438this string will be considered the most recently killed by a later 1439.Ic yank 1440command. Repeating 1441.Ic yank-pop 1442will cycle through the 1443killring any number of times. 1444.El 1445. 1446.Ss Lexical structure 1447The shell splits input lines into words at blanks and tabs. 1448The special 1449characters 1450.Ql \&& , 1451.Ql | , 1452.Ql \&; , 1453.Ql < , 1454.Ql > , 1455.Ql \&( , 1456and 1457.Ql \&) , 1458and the doubled characters 1459.Ql && , 1460.Ql || , 1461.Ql << , 1462and 1463.Ql >> 1464are always separate words, whether or not they are 1465surrounded by whitespace. 1466.Pp 1467When the shell's input is not a terminal, the character 1468.Ql # 1469is taken to begin a 1470comment. 1471Each 1472.Ql # 1473and the rest of the input line on which it appears is 1474discarded before further parsing. 1475.Pp 1476A special character (including a blank or tab) may be prevented from having 1477its special meaning, and possibly made part of another word, by preceding it 1478with a backslash 1479.Pq Ql \e 1480or enclosing it in single 1481.Pq Ql \&' , 1482double 1483.Pq Ql \&" , 1484or 1485backward 1486.Pq Ql \&` 1487quotes. 1488When not otherwise quoted a newline preceded by a 1489.Ql \e 1490is equivalent to a blank, but inside quotes this sequence results in a 1491newline. 1492.Pp 1493Furthermore, all 1494.Sx Substitutions 1495(see below) except 1496.Sx History substitution 1497can be prevented by enclosing the strings (or parts of strings) 1498in which they appear with single quotes or by quoting the crucial character(s) 1499(e.g., 1500.Ql $ 1501or 1502.Ql \&` 1503for 1504.Sx Variable substitution 1505or 1506.Sx Command substitution 1507respectively) 1508with 1509.Ql \e . 1510.Sx ( Alias substitution 1511is no exception: quoting in any way any 1512character of a word for which an 1513.Ic alias 1514has been defined prevents 1515substitution of the alias. 1516The usual way of quoting an alias is to precede it 1517with a backslash.) 1518.Sx History substitution 1519is prevented by 1520backslashes but not by single quotes. 1521Strings quoted with double or backward 1522quotes undergo 1523.Sx Variable substitution 1524and 1525.Sx Command substitution , 1526but other substitutions are prevented. 1527.Pp 1528Text inside single or double quotes becomes a single word (or part of one). 1529Metacharacters in these strings, including blanks and tabs, do not form 1530separate words. 1531Only in one special case (see 1532.Sx Command substitution 1533below) can a double-quoted string yield parts of more than one word; 1534single-quoted strings never do. 1535Backward quotes are special: they signal 1536.Sx Command substitution 1537(q.v.), which may result in more than one word. 1538.Pp 1539C-style escape sequences can be used in single quoted strings by 1540preceding the leading quote with 1541.Ql $ . 1542(+) 1543See 1544.Sx Escape sequences 1545for 1546a complete list of recognized escape sequences. 1547.Pp 1548Quoting complex strings, particularly strings which themselves contain quoting 1549characters, can be confusing. 1550Remember that quotes need not be used as they are 1551in human writing! 1552It may be easier to quote not an entire string, but only 1553those parts of the string which need quoting, using different types of quoting 1554to do so if appropriate. 1555.Pp 1556The 1557.Ic backslash_quote 1558shell variable (q.v.) can be set to make backslashes 1559always quote 1560.Ql \e , 1561.Ql \&' , 1562and 1563.Ql \&" 1564(+). This may make complex quoting tasks 1565easier, but it can cause syntax errors in 1566.Xr csh 1 1567scripts. 1568. 1569.Ss Escape sequences (+) 1570The following escape sequences are always recognized inside a string 1571constructed using 1572.Ql $'' , 1573and optionally by the 1574.Ic echo 1575builtin command as 1576controlled by the 1577.Ic echo_style 1578shell variable. 1579.Pp 1580Supported escape sequences are: 1581.Pp 1582.Bl -tag -width 12n -offset indent -compact 1583.It Li \ea 1584Bell. 1585.It Li \eb 1586Backspace. 1587.It Li \ec Ns Ar c 1588The control character denoted by 1589.Ql ^ Ns Ar c 1590in 1591.Xr stty 1 . 1592If 1593.Ar c 1594is a backslash, it must be doubled. 1595.It Li \ee 1596Escape. 1597.It Li \ef 1598Form feed. 1599.It Li \en 1600Newline. 1601.It Li \er 1602Carriage return. 1603.It Li \et 1604Horizontal tab. 1605.It Li \ev 1606Vertical tab. 1607.It Li \e\e 1608Literal backslash. 1609.It Li \e\&' 1610Literal single quote. 1611.It Li \e\&" 1612Literal double quote. 1613.It Li \e Ns Ar nnn 1614The character corresponding to the octal number 1615.Ar nnn . 1616.It Li \ex Ns Ar nn 1617The character corresponding to the hexadecimal number 1618.Ar nn 1619(1\-2 hexadecimal digits). 1620.It Li \ex{ Ns Ar nnnnnnnn Ns Li } 1621The character corresponding to the hexadecimal number 1622.Ar nnnnnnnn 1623(1\-8 hexadecimal digits). 1624.It Li \eu Ns Ar nnnn 1625The Unicode code point 1626.Ar nnnn 1627(1\-4 hexadecimal digits). 1628.It Li \eU Ns Ar nnnnnnnn 1629The Unicode code point 1630.Ar nnnnnnnn 1631(1\-8 hexadecimal digits). 1632.El 1633.Pp 1634The implementations of 1635.Ql \ex , 1636.Ql \eu , 1637and 1638.Ql \eU 1639in other shells may take a varying number of digits. It is often safest 1640to use leading zeros to provide the maximum expected number of digits. 1641. 1642.Ss Substitutions 1643We now describe the various transformations the shell performs on the input in 1644the order in which they occur. 1645We note in passing the data structures involved 1646and the commands and variables which affect them. 1647Remember that substitutions 1648can be prevented by quoting as described under 1649.Sx Lexical structure . 1650. 1651.Ss History substitution 1652Each command, or 1653.Dq event , 1654input from the terminal is saved in the history list. 1655The previous command is always saved, and the 1656.Ic history 1657shell 1658variable can be set to a number to save that many commands. 1659The 1660.Ic histdup 1661shell variable can be set to not save duplicate events or consecutive duplicate 1662events. 1663.Pp 1664Saved commands are numbered sequentially from 1 and stamped with the time. 1665It is not usually necessary to use event numbers, but the current event number 1666can be made part of the prompt by placing an 1667.Ql \&! 1668in the 1669.Ic prompt 1670shell variable. 1671.Pp 1672By default history entries are displayed by printing each parsed token 1673separated by space; thus the redirection operator 1674.Ql >\&&\&! 1675will be displayed as 1676.Ql >\0\&&\0\&! . 1677The shell actually saves history in expanded and literal (unexpanded) forms. 1678If the 1679.Ic histlit 1680shell variable is set, commands that display and store 1681history use the literal form. 1682.Pp 1683The 1684.Ic history 1685builtin command can print, store in a file, restore 1686and clear the history list at any time, 1687and the 1688.Ic savehist 1689and 1690.Ic histfile 1691shell variables can be set to 1692store the history list automatically on logout and restore it on login. 1693.Pp 1694History substitutions introduce words from the history list into the input 1695stream, making it easy to repeat commands, repeat arguments of a previous 1696command in the current command, or fix spelling mistakes in the previous 1697command with little typing and a high degree of confidence. 1698.Pp 1699History substitutions begin with the character 1700.Ql \&! . 1701They may begin anywhere in 1702the input stream, but they do not nest. 1703The 1704.Ql \&! 1705may be preceded by a 1706.Ql \e 1707to 1708prevent its special meaning; for convenience, a 1709.Ql \&! 1710is passed unchanged when it 1711is followed by a blank, tab, newline, 1712.Ql = 1713or 1714.Ql \&( . 1715History substitutions also 1716occur when an input line begins with 1717.Ql ^ . 1718This special abbreviation will be 1719described later. 1720The characters used to signal history substitution 1721.Po 1722.Ql \&! 1723and 1724.Ql ^ 1725.Pc 1726can be changed by setting the 1727.Ic histchars 1728shell variable. 1729Any input 1730line which contains a history substitution is printed before it is executed. 1731.Pp 1732A history substitution may have an 1733.Dq event specification , 1734which indicates the event from which words are to be taken, a 1735.Dq word designator , 1736which selects particular words from the chosen event, and/or a 1737.Dq modifier , 1738which manipulates the selected words. 1739.Pp 1740An event specification can be: 1741.Pp 1742.Bl -tag -width 5n -offset indent -compact 1743. 1744.It Ar n 1745A number, referring to a particular event. 1746. 1747.It Li \- Ns Ar n 1748An offset, referring to the event 1749.Ar n 1750before the current event. 1751. 1752.It Li # 1753The current event. 1754This should be used carefully in 1755.Xr csh 1 , 1756where there is no check for recursion. 1757.Nm 1758allows 10 levels of recursion. (+) 1759. 1760.It Li \&! 1761The previous event (equivalent to 1762.Ql \-1 ) . 1763. 1764.It Ar s 1765The most recent event whose first word begins with the string 1766.Ar s . 1767. 1768.It Li ? Ns Ar s Ns Li ? 1769The most recent event which contains the string 1770.Ar s . 1771The second 1772.Ql \&? 1773can be omitted if it is immediately followed by a newline. 1774.El 1775.Pp 1776For example, consider this bit of someone's history list: 1777.Bd -literal -offset indent 1778 9 8:30 nroff \-man wumpus.man 177910 8:31 cp wumpus.man wumpus.man.old 178011 8:36 vi wumpus.man 178112 8:37 diff wumpus.man.old wumpus.man 1782.Ed 1783.Pp 1784The commands are shown with their event numbers and time stamps. 1785The current event, which we haven't typed in yet, is event 13. 1786.Ql !11 1787and 1788.Ql !\-2 1789refer to event 11. 1790.Ql \&!! 1791refers to the previous event, 12. 1792.Ql \&!! 1793can be abbreviated 1794.Ql \&! 1795if it is 1796followed by 1797.Ql \&: 1798.Po 1799.Ql \&: 1800is described below 1801.Pc . 1802.Ql !n 1803refers to event 9, which begins with 1804.Ql n . 1805.Ql !?old? 1806also refers to event 12, which contains 1807.Ql old . 1808Without word designators or modifiers history references simply expand to the 1809entire event, so we might type 1810.Ql !cp 1811to redo the copy command or 1812.Ql !!|more 1813if the 1814.Ql diff 1815output scrolled off the top of the screen. 1816.Pp 1817History references may be insulated from the surrounding text with braces if 1818necessary. 1819For example, 1820.Ql !vdoc 1821would look for a command beginning with 1822.Ql vdoc , 1823and, in this example, not find one, but 1824.Ql !{v}doc 1825would expand 1826unambiguously to 1827.Ql vi wumpus.mandoc . 1828Even in braces, history substitutions do not nest. 1829.Pp 1830(+) While 1831.Xr csh 1 1832expands, for example, 1833.Ql !3d 1834to event 3 with the 1835letter 1836.Ql d 1837appended to it, 1838.Nm 1839expands it to the last event beginning 1840with 1841.Ql 3d ; 1842only completely numeric arguments are treated as event numbers. 1843This makes it possible to recall events beginning with numbers. 1844To expand 1845.Ql !3d 1846as in 1847.Xr csh 1 1848type 1849.Ql !{3}d . 1850.Pp 1851To select words from an event we can follow the event specification by a 1852.Ql \&: 1853and a designator for the desired words. 1854The words of an input line are 1855numbered from 0, the first (usually command) word being 0, the second word 1856(first argument) being 1, etc. 1857.Pp 1858The basic word designators are: 1859.Pp 1860.Bl -tag -width 4n -offset indent -compact 1861. 1862.It Li 0 1863The first (command) word. 1864. 1865.It Ar n 1866The 1867.Ar n Ns 1868th argument. 1869. 1870.It Li ^ 1871The first argument, equivalent to 1872.Ql 1 . 1873. 1874.It Li $ 1875The last argument. 1876. 1877.It Li % 1878The word matched by an 1879.Li ? Ns Ar s Ns Li ? No search. 1880. 1881.It Ar x Ns Li \- Ns Ar y 1882A range of words. 1883. 1884.It Li \- Ns Ar y 1885Equivalent to 1886.Ql 0\- Ns Ar y . 1887. 1888.It Li * 1889Equivalent to 1890.Ql ^\-$ , 1891but returns nothing if the event contains only 1 word. 1892. 1893.It Ar x Ns Li * 1894Equivalent to 1895.Sq Ar x Ns Li \-$ . 1896. 1897.It Ar x Ns Li \- 1898Equivalent to 1899.Sq Ar x Ns Li * , 1900but omitting the last word 1901.Pq Ql $ . 1902.El 1903.Pp 1904Selected words are inserted into the command line separated by single blanks. 1905For example, the 1906.Ql diff 1907command in the previous example might have been 1908typed as 1909.Ql diff !!:1.old !!:1 1910(using 1911.Ql \&:1 1912to select the first argument 1913from the previous event) or 1914.Ql diff !\-2:2 !\-2:1 1915to select and swap the 1916arguments from the 1917.Ql cp 1918command. 1919If we didn't care about the order of the 1920.Ql diff 1921we might have said 1922.Ql diff !\-2:1\-2 1923or simply 1924.Ql diff !\-2:* . 1925The 1926.Ql cp 1927command might have been written 1928.Ql cp wumpus.man !#:1.old , 1929using 1930.Ql # 1931to refer to the current event. 1932.Ql !n:\- hurkle.man 1933would reuse the first two words from the 1934.Ql nroff 1935command 1936to type 1937.Ql nroff \-man hurkle.man . 1938.Pp 1939The 1940.Ql \&: 1941separating the event specification from the word designator can be 1942omitted if the argument selector begins with a 1943.Ql ^ , 1944.Ql $ , 1945.Ql * , 1946.Ql % , 1947or 1948.Ql \- . 1949For example, our 1950.Ql diff 1951command might have been 1952.Ql diff !!^.old !!^ 1953or, 1954equivalently, 1955.Ql diff !!$.old !!$ . 1956However, if 1957.Ql \&!! 1958is abbreviated 1959.Ql \&! , 1960an argument selector beginning with 1961.Ql \- 1962will be interpreted as an event 1963specification. 1964.Pp 1965A history reference may have a word designator but no event specification. 1966It then references the previous command. 1967Continuing our 1968.Ql diff 1969example, we could have said simply 1970.Ql diff !^.old !^ 1971or, to get the arguments in the opposite order, just 1972.Ql diff !* . 1973.Pp 1974The word or words in a history reference can be edited, or 1975.Dq modified , 1976by following it with one or more modifiers, each preceded by a 1977.Ql \&: : 1978.Pp 1979.Bl -tag -width 6n -offset indent -compact 1980. 1981.It Li h 1982Remove a trailing pathname component, leaving the head. 1983. 1984.It Li t 1985Remove all leading pathname components, leaving the tail. 1986. 1987.It Li r 1988Remove a filename extension 1989.Sq . Ns Ar xxx , 1990leaving the root name. 1991. 1992.It Li e 1993Remove all but the extension. 1994. 1995.It Li u 1996Uppercase the first lowercase letter. 1997. 1998.It Li l 1999Lowercase the first uppercase letter. 2000. 2001.It Li s/ Ns Ar l Ns Li / Ns Ar r Ns Li / 2002Substitute 2003.Ar l 2004for 2005.Ar r . 2006.Ar l 2007is simply a string like 2008.Ar r , 2009not a regular expression as in 2010the eponymous 2011.Xr ed 1 2012command. 2013Any character may be used as the delimiter in place of 2014.Ql / ; 2015a 2016.Ql \e 2017can be used to quote the delimiter inside 2018.Ar l 2019and 2020.Ar r 2021The character 2022.Ql & 2023in the 2024.Ar r 2025is replaced by 2026.Ar l ; 2027.Ql \e 2028also quotes 2029.Ql & . 2030If 2031.Ar l 2032is empty 2033.Sq ( \& ) , 2034the 2035.Ar l 2036from a previous substitution or the 2037.Ar s 2038from a previous search or event number in event specification is used. 2039The trailing delimiter may be omitted if it is immediately followed by a 2040newline. 2041. 2042.It Li \&& 2043Repeat the previous substitution. 2044. 2045.It Li g 2046Apply the following modifier once to each word. 2047. 2048.It Li a No (+) 2049Apply the following modifier as many times as possible to a single word. 2050.Ql a 2051and 2052.Ql g 2053can be used together to apply a modifier globally. 2054With the 2055.Ql s 2056modifier, only the patterns contained in the original word are 2057substituted, not patterns that contain any substitution result. 2058. 2059.It Li p 2060Print the new command line but do not execute it. 2061. 2062.It Li q 2063Quote the substituted words, preventing further substitutions. 2064. 2065.It Li Q 2066Same as 2067.Ql q 2068but in addition preserve empty variables as a string containing a NUL. 2069This is useful to preserve positional arguments for example: 2070.Bd -literal -offset indent -compact 2071> set args=('arg 1' '' 'arg 3') 2072> tcsh -f -c 'echo ${#argv}' $args:gQ 20733 2074.Ed 2075. 2076.It Li x 2077Like 2078.Ql q , 2079but break into words at blanks, tabs and newlines. 2080.El 2081.Pp 2082Modifiers are applied to only the first modifiable word (unless 2083.Ql g 2084is used). 2085It is an error for no word to be modifiable. 2086.Pp 2087For example, the 2088.Ql diff 2089command might have been written as 2090.Ql diff wumpus.man.old !#^:r , 2091using 2092.Ql \&:r 2093to remove 2094.Ql .old 2095from the first argument on the same line 2096(`!#^'). 2097We could type 2098.Ql echo hello out there , 2099then 2100.Ql echo !*:u 2101to capitalize 2102.Ql hello , 2103.Ql echo !*:au 2104to upper case the first word to 2105.QL HELLO , 2106or 2107.Ql echo !*:agu 2108to upper case all words. 2109We might follow 2110.Ql mail \-s \&"I forgot my password\&" rot 2111with 2112.Ql !:s/rot/root 2113to 2114correct the spelling of 2115.Ql root 2116(but see 2117.Sx Spelling correction 2118for a 2119different approach). 2120.Pp 2121There is a special abbreviation for substitutions. 2122.Ql ^ , 2123when it is the first character on an input line, is equivalent to 2124.Ql !:s^ . 2125Thus we might have said 2126.Ql ^rot^root 2127to make the spelling correction in the 2128previous example. 2129This is the only history substitution which does not explicitly begin with 2130.Ql \&! . 2131.Pp 2132(+) In 2133.Xr csh 1 2134as such, only one modifier may be applied to each history 2135or variable expansion. 2136In 2137.Nm , 2138more than one may be used, for example 2139.Bd -literal -offset indent 2140% mv wumpus.man /usr/share/man/man1/wumpus.1 2141% man !$:t:r 2142man wumpus 2143.Ed 2144.Pp 2145In 2146.Xr csh 1 , 2147the result would be 2148.Ql wumpus.1:r . 2149A substitution followed by a 2150colon may need to be insulated from it with braces: 2151.Bd -literal -offset indent 2152> mv a.out /usr/games/wumpus 2153> setenv PATH !$:h:$PATH 2154Bad ! modifier: $. 2155> setenv PATH !{\-2$:h}:$PATH 2156setenv PATH /usr/games:/bin:/usr/bin:. 2157.Ed 2158.Pp 2159The first attempt would succeed in 2160.Xr csh 1 2161but fails in 2162.Nm , 2163because 2164.Nm 2165expects another modifier after the second colon 2166rather than 2167.Ql $ . 2168.Pp 2169Finally, history can be accessed through the editor as well as through 2170the substitutions just described. 2171The 2172.Ic up-history 2173and 2174.Ic down-history , 2175.Ic history-search-backward 2176and 2177.Ic history-search-forward , 2178.Ic i-search-back 2179and 2180.Ic i-search-fwd , 2181.Ic vi-search-back 2182and 2183.Ic vi-search-fwd , 2184.Ic copy-prev-word 2185and 2186.Ic insert-last-word 2187editor commands search for 2188events in the history list and copy them into the input buffer. 2189The 2190.Ic toggle-literal-history 2191editor command switches between the 2192expanded and literal forms of history lines in the input buffer. 2193.Ic expand-history 2194and 2195.Ic expand-line 2196expand history substitutions 2197in the current word and in the entire input buffer respectively. 2198. 2199.Ss Alias substitution 2200The shell maintains a list of aliases which can be set, unset and printed by 2201the 2202.Ic alias 2203and 2204.Ic unalias 2205commands. 2206After a command line is parsed 2207into simple commands (see 2208.Sx Commands ) 2209the first word of each command, 2210left-to-right, is checked to see if it has an alias. 2211If so, the first word is 2212replaced by the alias. 2213If the alias contains a history reference, it undergoes 2214.Sx History substitution 2215(q.v.) as though the original command were the 2216previous input line. 2217If the alias does not contain a history reference, the 2218argument list is left untouched. 2219.Pp 2220Thus if the alias for 2221.Ql ls 2222were 2223.Ql ls \-l 2224the command 2225.Ql ls /usr 2226would become 2227.Ql ls \-l /usr , 2228the argument list here being undisturbed. 2229If the alias for 2230.Ql lookup 2231were 2232.Ql grep !^ /etc/passwd 2233then 2234.Ql lookup bill 2235would become 2236.Ql grep bill /etc/passwd . 2237Aliases can be used to introduce parser metasyntax. 2238For example, 2239.Sq alias print 'pr \e!* | lpr' 2240defines a 2241.Dq command 2242.Pq Ql print 2243which 2244.Xr pr 1 Ns s 2245its arguments to the line printer. 2246.Pp 2247Alias substitution is repeated until the first word of the command has no 2248alias. 2249If an alias substitution does not change the first word (as in the 2250previous example) it is flagged to prevent a loop. 2251Other loops are detected and 2252cause an error. 2253.Pp 2254Some aliases are referred to by the shell; see 2255.Sx Special aliases . 2256. 2257.Ss Variable substitution 2258The shell maintains a list of variables, each of which has as value a list of 2259zero or more words. 2260The values of shell variables can be displayed and changed with the 2261.Ic set 2262and 2263.Ic unset 2264commands. 2265The system maintains its own list of 2266.Dq environment 2267variables. 2268These can be displayed and changed with 2269.Ic printenv , 2270.Ic setenv , 2271and 2272.Ic unsetenv . 2273.Pp 2274(+) Variables may be made read-only with 2275.Ql set \-r 2276(q.v.). 2277Read-only variables may not be modified or unset; 2278attempting to do so will cause an error. 2279Once made read-only, a variable cannot be made writable, 2280so 2281.Ql set \-r 2282should be used with caution. 2283Environment variables cannot be made read-only. 2284.Pp 2285Some variables are set by the shell or referred to by it. 2286For instance, the 2287.Ic argv 2288variable is an image of the shell's argument 2289list, and words of this variable's value are referred to in special ways. 2290Some of the variables referred to by the shell are toggles; 2291the shell does not care what their value is, only whether they are set or not. 2292For instance, the 2293.Ic verbose 2294variable is a toggle which causes command 2295input to be echoed. 2296The 2297.Fl v 2298command line option sets this variable. 2299.Sx Special shell variables 2300lists all variables which are referred to by the shell. 2301.Pp 2302Other operations treat variables numerically. 2303The 2304.Sq Ic @ 2305command permits numeric 2306calculations to be performed and the result assigned to a variable. 2307Variable 2308values are, however, always represented as (zero or more) strings. 2309For the 2310purposes of numeric operations, the null string is considered to be zero, and 2311the second and subsequent words of multi-word values are ignored. 2312.Pp 2313After the input line is aliased and parsed, and before each command is 2314executed, variable substitution is performed keyed by 2315.Ql $ 2316characters. 2317This 2318expansion can be prevented by preceding the 2319.Ql $ 2320with a 2321.Ql \e 2322except within 2323.Ql \&" 2324pairs where it 2325.Em always 2326occurs, and within 2327.Ql \&' 2328pairs where it 2329.Em never 2330occurs. 2331Strings quoted by 2332.Ql \` 2333are interpreted later (see 2334.Sx Command substitution 2335below) so 2336.Ql $ 2337substitution does not occur there until later, 2338if at all. 2339A 2340.Ql $ 2341is passed unchanged if followed by a blank, tab, or 2342end-of-line. 2343.Pp 2344Input/output redirections are recognized before variable expansion, and are 2345variable expanded separately. 2346Otherwise, the command name and entire argument 2347list are expanded together. 2348It is thus possible for the first (command) word 2349(to this point) to generate more than one word, the first of which becomes the 2350command name, and the rest of which become arguments. 2351.Pp 2352Unless enclosed in 2353.Ql \&" 2354or given the 2355.Ql \&:q 2356modifier the results of variable 2357substitution may eventually be command and filename substituted. 2358Within 2359.Ql \&" , 2360a 2361variable whose value consists of multiple words expands to a (portion of a) 2362single word, with the words of the variable's value separated by blanks. 2363When 2364the 2365.Ql \&:q 2366modifier is applied to a substitution the variable will expand to 2367multiple words with each word separated by a blank and quoted to prevent later 2368command or filename substitution. 2369.Pp 2370The following metasequences are provided for introducing variable values into 2371the shell input: 2372.Pp 2373.Bl -tag -width 10n -offset indent -compact 2374. 2375.It Li $ Ns Ar name 2376.It Li ${ Ns Ar name Ns Li } 2377Substitutes the words of the value of variable 2378.Ar name , 2379each separated 2380by a blank. 2381Braces insulate 2382.Ar name 2383from following characters which would 2384otherwise be part of it. 2385Shell variables have names consisting of 2386letters and digits starting with a letter. 2387The underscore character is 2388considered a letter. 2389If 2390.Ar name 2391is not a shell variable, but is set in the 2392environment, then that value is returned (but some of the other forms 2393given below are not available in this case). 2394. 2395.Pp 2396.It Li $ Ns Ar name Ns Li [ Ns Ar selector Ns Li ] 2397.It Li ${ Ns Ar name Ns Li [ Ns Ar selector Ns Li ]} 2398Substitutes only the selected words from the value of 2399.Ar name . 2400The 2401.Ar selector 2402is subjected to 2403.Ql $ 2404substitution and may consist of 2405a single number or two numbers separated by a 2406.Ql \- . 2407The first word of a variable's value is numbered 2408.Ql 1 . 2409If the first number of a range is omitted it defaults to 2410.Ql 1 . 2411If the last member of a range is omitted it defaults to 2412.Ql $# Ns Ar name . 2413The 2414.Ar selector 2415.Ql * 2416selects all words. 2417It is not an error for a range to be empty if the 2418second argument is omitted or in range. 2419. 2420.Pp 2421.It Li $0 2422Substitutes the name of the file from which command input 2423is being read. 2424An error occurs if the name is not known. 2425. 2426.Pp 2427.It Li $ Ns Ar number 2428.It Li ${ Ns Ar number Ns Li } 2429Equivalent to 2430.Ql $argv[ Ns Ar number Ns Li \] . 2431. 2432.Pp 2433.It Li $* 2434Equivalent to 2435.Ql $argv , 2436which is equivalent to 2437.Ql $argv[*] . 2438.El 2439.Pp 2440Except as noted, it is an error to reference a variable which 2441is not set. 2442.Pp 2443The 2444.Ql \&: 2445modifiers described under 2446.Sx History substitution , 2447except for 2448.Ql \&:p , 2449can be applied to the substitutions above. 2450More than one may be used. 2451(+) 2452Braces may be needed to insulate a variable substitution from a literal colon 2453just as with 2454.Sx History substitution 2455(q.v.); any modifiers must appear 2456within the braces. 2457.Pp 2458The following substitutions can not be modified with 2459.Ql \&: 2460modifiers: 2461.Pp 2462.Bl -tag -width 10n -offset indent -compact 2463. 2464.It Li $? Ns Ar name 2465.It Li ${? Ns Ar name Ns Li } 2466Substitutes the string 2467.Ql 1 2468if 2469.Ar name 2470is set, 2471.Ql 0 2472if it is not. 2473. 2474.Pp 2475.It Li $?0 2476Substitutes 2477.Ql 1 2478if the current input filename is known, 2479.Ql 0 2480if it is not. 2481Always 2482.Ql 0 2483in interactive shells. 2484. 2485.Pp 2486.It Li $# Ns Ar name 2487.It Li ${# Ns Ar name Ns Li } 2488Substitutes the number of words in 2489.Ar name . 2490. 2491.Pp 2492.It Li $# 2493Equivalent to 2494.Ql $#argv . 2495(+) 2496. 2497.Pp 2498.It Li $% Ns Ar name 2499.It Li ${% Ns Ar name Ns Li } 2500Substitutes the number of characters in 2501.Ar name . 2502(+) 2503. 2504.Pp 2505.It Li $% Ns Ar number 2506.It Li ${% Ns Ar number Ns Li } 2507Substitutes the number of characters in 2508.Ql $argv[ Ns Ar number Ns Li \] . 2509(+) 2510. 2511.Pp 2512.It Li $? 2513Equivalent to 2514.Ql $status . 2515(+) 2516. 2517.Pp 2518.It Li $$ 2519Substitutes the (decimal) process number of the (parent) shell. 2520. 2521.Pp 2522.It Li $! 2523Substitutes the (decimal) process number of the last 2524background process started by this shell. 2525(+) 2526. 2527.Pp 2528.It Li $_ 2529Substitutes the command line of the last command executed. 2530(+) 2531. 2532.Pp 2533.It Li $< 2534Substitutes a line from the standard input, with no further interpretation 2535thereafter. 2536It can be used to read from the keyboard in a shell script. 2537(+) While 2538.Xr csh 1 2539always quotes 2540.Ql $< , 2541as if it were equivalent to 2542.Ql $<:q , 2543.Nm 2544does not. 2545Furthermore, when 2546.Nm 2547is waiting for a line to be 2548typed the user may type an interrupt to interrupt the sequence into 2549which the line is to be substituted, but 2550.Xr csh 1 2551does not allow this. 2552.El 2553.Pp 2554The editor command 2555.Ic expand-variables , 2556normally bound to 2557.Sq ^X-$ , 2558can be used to interactively expand individual variables. 2559. 2560.Ss "Command, filename and directory stack substitution" 2561The remaining substitutions are applied selectively to the arguments 2562of builtin commands. 2563This means that portions of expressions which are not evaluated are 2564not subjected to these expansions. 2565For commands which are not internal to the 2566shell, the command name is substituted separately from the argument list. 2567This occurs very late, after input-output redirection is performed, and 2568in a child of the main shell. 2569. 2570.Ss "Command substitution" 2571Command substitution is indicated by a command enclosed in 2572.Ql \&` . 2573The output 2574from such a command is broken into separate words at blanks, tabs and newlines, 2575and null words are discarded. 2576The output is variable and command substituted 2577and put in place of the original string. 2578.Pp 2579Command substitutions inside double 2580quotes 2581.Pq Ql \&" 2582retain blanks and tabs; only newlines force new words. 2583The single 2584final newline does not force a new word in any case. 2585It is thus possible for a 2586command substitution to yield only part of a word, even if the command outputs 2587a complete line. 2588.Pp 2589By default, the shell since version 6.12 replaces all newline and carriage 2590return characters in the command by spaces. 2591If this is switched off by 2592unsetting 2593.Ic csubstnonl , 2594newlines separate commands as usual. 2595. 2596.Ss "Filename substitution" 2597If a word contains any of the characters 2598.Ql * , 2599.Ql \&? , 2600.Ql \&[ , 2601or 2602.Ql { 2603or begins with 2604the character 2605.Ql ~ 2606it is a candidate for filename substitution, also known as 2607.Dq globbing . 2608This word is then regarded as a pattern 2609.Dq ( glob-pattern ) , 2610and 2611replaced with an alphabetically sorted list of file names which match the 2612pattern. 2613.Pp 2614In matching filenames, the character 2615.Ql \&. 2616at the beginning of a filename or 2617immediately following a 2618.Ql / , 2619as well as the character 2620.Ql / 2621must be matched 2622explicitly (unless either 2623.Ic globdot 2624or 2625.Ic globstar 2626or both are set (+)). 2627The character 2628.Ql * 2629matches any string of characters, 2630including the null string. 2631The character 2632.Ql \&? 2633matches any single character. 2634The sequence 2635.Ql [...] 2636matches any one of the characters enclosed. 2637Within 2638.Ql [...] , 2639a pair of 2640characters separated by 2641.Ql \- 2642matches any character lexically between the two. 2643.Pp 2644(+) Some glob-patterns can be negated: 2645The sequence 2646.Ql [^...] 2647matches any single character 2648.Em not 2649specified by the 2650characters and/or ranges of characters in the braces. 2651.Pp 2652An entire glob-pattern can also be negated with 2653.Ql ^ : 2654.Bd -literal -offset indent 2655> echo * 2656bang crash crunch ouch 2657> echo ^cr* 2658bang ouch 2659.Ed 2660.Pp 2661Glob-patterns which do not use 2662.Ql \&? , 2663.Ql * , 2664or 2665.Ql [] , 2666or which use 2667.Ql {} 2668or 2669.Ql ~ 2670(below) are not negated correctly. 2671.Pp 2672The metanotation 2673.Ql a{b,c,d}e 2674is a shorthand for 2675.Ql abe ace ade . 2676Left-to-right order is preserved: 2677.Ql /usr/source/s1/{oldls,ls}.c 2678expands 2679to 2680.Ql /usr/source/s1/oldls.c /usr/source/s1/ls.c . 2681The results of matches are 2682sorted separately at a low level to preserve this order: 2683.Ql ../{memo,*box} 2684might expand to 2685.Ql ../memo ../box ../mbox . 2686(Note that 2687.Ql memo 2688was not sorted with the results of matching 2689.Ql *box . ) 2690It is not an error when this construct expands to files which do not exist, 2691but it is possible to get an error from a command to which the expanded list 2692is passed. 2693This construct may be nested. 2694As a special case the words 2695.Ql { , 2696.Ql } , 2697and 2698.Ql {} 2699are passed undisturbed. 2700.Pp 2701The character 2702.Ql ~ 2703at the beginning of a filename refers to home directories. 2704Standing alone, i.e., 2705.Ql ~ , 2706it expands to the invoker's home directory as 2707reflected in the value of the 2708.Ic home 2709shell variable. 2710When followed by a 2711name consisting of letters, digits and 2712.Ql \- 2713characters the shell searches for a 2714user with that name and substitutes their home directory; thus 2715.Ql ~ken 2716might 2717expand to 2718.Ql /usr/ken 2719and 2720.Ql ~ken/chmach 2721to 2722.Ql /usr/ken/chmach . 2723If the character 2724.Ql ~ 2725is followed by a character other than a letter or 2726.Ql / 2727or appears elsewhere 2728than at the beginning of a word, it is left undisturbed. 2729A command like 2730.Ql setenv MANPATH /usr/share/man:/usr/local/share/man:~/lib/man 2731does not, 2732therefore, do home directory substitution as one might hope. 2733.Pp 2734It is an error for a glob-pattern containing 2735.Ql * , 2736.Ql \&? , 2737.Ql \&[ , 2738or 2739.Ql ~ , 2740with or 2741without 2742.Ql ^ , 2743not to match any files. 2744However, only one pattern in a list of 2745glob-patterns must match a file (so that, e.g., 2746.Ql rm *.a *.c *.o 2747would fail 2748only if there were no files in the current directory ending in 2749.Ql .a , 2750.Ql .c , 2751or 2752.Ql .o ) , 2753and if the 2754.Ic nonomatch 2755shell variable is set a pattern (or list 2756of patterns) which matches nothing is left unchanged rather than causing 2757an error. 2758.Pp 2759The 2760.Ic globstar 2761shell variable can be set to allow 2762.Ql ** 2763or 2764.Ql *** 2765as 2766a file glob pattern that matches any string of characters including 2767.Ql / , 2768recursively traversing any existing sub-directories. 2769For example, 2770.Ql ls **.c 2771will list all the .c files in the current directory tree. 2772If used by itself, it will match zero or more sub-directories 2773(e.g. 2774.Ql ls /usr/include/**/time.h 2775will list any file named 2776.Ql time.h 2777in the 2778.Pa /usr/include 2779directory tree; 2780.Ql ls /usr/include/**time.h 2781will match 2782any file in the 2783.Pa /usr/include 2784directory tree ending in 2785.Ql time.h ; 2786and 2787.Ql ls /usr/include/**time**.h 2788will match any .h file with 2789.Ql time 2790either 2791in a subdirectory name or in the filename itself). 2792To prevent problems with recursion, the 2793.Ql ** 2794glob-pattern will not 2795descend into a symbolic link containing a directory. 2796To override this, 2797use 2798.Ql *** 2799(+) 2800.Pp 2801The 2802.Ic noglob 2803shell variable can be set to prevent filename substitution, 2804and the 2805.Ic expand-glob 2806editor command, normally bound to 2807.Sq ^X-* , 2808can be 2809used to interactively expand individual filename substitutions. 2810. 2811.Ss "Directory stack substitution (+)" 2812The directory stack is a list of directories, numbered from zero, used by the 2813.Ic pushd , 2814.Ic popd , 2815and 2816.Ic dirs 2817builtin commands (q.v.). 2818.Ic dirs 2819can print, store in a file, restore and clear the directory stack 2820at any time, and the 2821.Ic savedirs 2822and 2823.Ic dirsfile 2824shell variables can be set to 2825store the directory stack automatically on logout and restore it on login. 2826The 2827.Ic dirstack 2828shell variable can be examined to see the directory stack and 2829set to put arbitrary directories into the directory stack. 2830.Pp 2831The character 2832.Ql = 2833followed by one or more digits expands to an entry in 2834the directory stack. 2835The special case 2836.Ql =- 2837expands to the last directory in 2838the stack. 2839For example, 2840.Bd -literal -offset indent 2841> dirs \-v 28420 /usr/bin 28431 /usr/spool/uucp 28442 /usr/accts/sys 2845> echo =1 2846/usr/spool/uucp 2847> echo =0/calendar 2848/usr/bin/calendar 2849> echo =\- 2850/usr/accts/sys 2851.Ed 2852.Pp 2853The 2854.Ic noglob 2855and 2856.Ic nonomatch 2857shell variables and the 2858.Ic expand-glob 2859editor command apply to directory stack as well as filename substitutions. 2860. 2861.Ss "Other substitutions (+)" 2862There are several more transformations involving filenames, not strictly 2863related to the above but mentioned here for completeness. 2864.Em Any 2865filename may be expanded to a full path when the 2866.Ic symlinks 2867variable (q.v.) is set to 2868.Ql expand . 2869Quoting prevents this expansion, and 2870the 2871.Ic normalize-path 2872editor command does it on demand. 2873The 2874.Ic normalize-command 2875editor command expands commands in 2876.Ev PATH 2877into full paths on demand. 2878Finally, 2879.Ic cd 2880and 2881.Ic pushd 2882interpret 2883.Ql \- 2884as the old working directory 2885(equivalent to the shell variable 2886.Ic owd ) . 2887This is not a substitution at all, but an abbreviation recognized by only 2888those commands. 2889Nonetheless, it too can be prevented by quoting. 2890. 2891.Ss "Commands" 2892The next three sections describe how the shell executes commands and 2893deals with their input and output. 2894. 2895.Ss "Simple commands, pipelines and sequences" 2896A simple command is a sequence of words, the first of which specifies the 2897command to be executed. 2898A series of simple commands joined by 2899.Ql | 2900characters 2901forms a pipeline. 2902The output of each command in a pipeline is connected to the 2903input of the next. 2904.Pp 2905Simple commands and pipelines may be joined into sequences with 2906.Ql \&; , 2907and will 2908be executed sequentially. 2909Commands and pipelines can also be joined into 2910sequences with 2911.Ql || 2912or 2913.Ql && , 2914indicating, as in the C language, that the second 2915is to be executed only if the first fails or succeeds respectively. 2916.Pp 2917A simple command, pipeline or sequence may be placed in parentheses, 2918.Ql () , 2919to form a simple command, which may in turn be a component of a pipeline or 2920sequence. 2921A command, pipeline or sequence can be executed 2922without waiting for it to terminate by following it with an 2923.Ql \&& . 2924. 2925.Ss "Builtin and non-builtin command execution" 2926Builtin commands are executed within the shell. 2927If any component of a 2928pipeline except the last is a builtin command, the pipeline is executed 2929in a subshell. 2930.Pp 2931Parenthesized commands are always executed in a subshell. 2932.Bd -literal -offset indent 2933(cd; pwd); pwd 2934.Ed 2935.Pp 2936thus prints the 2937.Ic home 2938directory, leaving you where you were 2939(printing this after the home directory), while 2940.Bd -literal -offset indent 2941cd; pwd 2942.Ed 2943.Pp 2944leaves you in the 2945.Ic home 2946directory. 2947Parenthesized commands are most often 2948used to prevent 2949.Ic cd 2950from affecting the current shell. 2951.Pp 2952When a command to be executed is found not to be a builtin command the shell 2953attempts to execute the command via 2954.Xr execve 2 . 2955Each word in the variable 2956.Ic path 2957names a directory in which the shell will look for the 2958command. 2959If the shell is not given a 2960.Fl f 2961option, the shell 2962hashes the names in these directories into an internal table so that it will 2963try an 2964.Xr execve 2 2965in only a directory where there is a possibility that the 2966command resides there. 2967This greatly speeds command location when a large 2968number of directories are present in the search path. This hashing mechanism is 2969not used: 2970.Bl -enum -width 2n -offset indent 2971.It 2972If hashing is turned explicitly off via 2973.Ic unhash . 2974.It 2975If the shell was given a 2976.Fl f Ar argument . 2977.It 2978For each directory component of 2979.Ic path 2980which does not begin with a 2981.Ql / . 2982.It 2983If the command contains a 2984.Ql / . 2985.El 2986.Pp 2987In the above four cases the shell concatenates each component of the path 2988vector with the given command name to form a path name of a file which it 2989then attempts to execute it. If execution is successful, the search stops. 2990.Pp 2991If the file has execute permissions but is not an executable to the system 2992(i.e., it is neither an executable binary nor a script that specifies its 2993interpreter), then it is assumed to be a file containing shell commands and 2994a new shell is spawned to read it. 2995The 2996.Ic shell 2997special alias may be set 2998to specify an interpreter other than the shell itself. 2999.Pp 3000On systems which do not understand the 3001.Ql #! 3002script interpreter convention 3003the shell may be compiled to emulate it; see the 3004.Ic version 3005shell 3006variable. 3007If so, the shell checks the first line of the file to 3008see if it is of the form 3009.Ql #! Ns Ar interpreter arg Li \&... . 3010If it is, 3011the shell starts 3012.Ar interpreter 3013with the given 3014.Ar arg Ns 3015s and feeds the 3016file to it on standard input. 3017. 3018.Ss "Input/output" 3019The standard input and standard output of a command may be redirected with the 3020following syntax: 3021.Pp 3022.Bl -tag -width 8n -offset indent -compact 3023. 3024.It Li < Ar name 3025Open file 3026.Ar name 3027(which is first variable, command and filename 3028expanded) as the standard input. 3029. 3030.Pp 3031.It Li << Ar word 3032Read the shell input up to a line which is identical to 3033.Ar word . 3034.Ar word 3035is not subjected to variable, filename or command substitution, and each input 3036line is compared to 3037.Ar word 3038before any substitutions are done on this input 3039line. 3040Unless a quoting 3041.Ql \e , 3042.Ql \&" , 3043.Ql \&' , 3044or 3045.Ql \&` 3046appears in 3047.Ar word 3048variable and 3049command substitution is performed on the intervening lines, allowing 3050.Ql \e 3051to 3052quote 3053.Ql $ , 3054.Ql \e , 3055and 3056.Ql \&` . 3057Commands which are substituted have all blanks, tabs, 3058and newlines preserved, except for the final newline which is dropped. 3059The 3060resultant text is placed in an anonymous temporary file which is given to the 3061command as standard input. 3062.Pp 3063.It Li > Ar name 3064.It Li >! Ar name 3065.It Li >& Ar name 3066.It Li >&! Ar name 3067The file 3068.Ar name 3069is used as standard output. 3070If the file does not exist 3071then it is created; if the file exists, it is truncated, its previous contents 3072being lost. 3073.Pp 3074If the shell variable 3075.Ic noclobber 3076is set, then the file must not exist or be a 3077character special file (e.g., a terminal or 3078.Pa /dev/null ) 3079or an error results. 3080This helps prevent accidental destruction of files. 3081In this case the 3082.Ql \&! 3083forms 3084can be used to suppress this check. 3085If 3086.Ql notempty 3087is given in 3088.Ic noclobber , 3089.Ql > 3090is allowed on empty files; 3091if 3092.Ql ask 3093is given in 3094.Ic noclobber , 3095an interacive confirmation is presented, rather than an 3096error. 3097.Pp 3098The forms involving 3099.Ql \&& 3100route the diagnostic output into the specified file as 3101well as the standard output. 3102.Ar name 3103is expanded in the same way as 3104.Ql < 3105input filenames are. 3106.Pp 3107.It Li >> Ar name 3108.It Li >>& Ar name 3109.It Li >>! Ar name 3110.It Li >>&! Ar name 3111Like 3112.Ql > , 3113but appends output to the end of 3114.Ar name . 3115If the shell variable 3116.Ic noclobber 3117is set, then it is an error for 3118the file 3119.Em not 3120to exist, unless one of the 3121.Ql \&! 3122forms is given. 3123.El 3124.Pp 3125A command receives the environment in which the shell was invoked as modified 3126by the input-output parameters and the presence of the command in a pipeline. 3127Thus, unlike some previous shells, commands run from a file of shell commands 3128have no access to the text of the commands by default; rather they receive the 3129original standard input of the shell. 3130The 3131.Ql << 3132mechanism should be used to 3133present inline data. 3134This permits shell command scripts to function as 3135components of pipelines and allows the shell to block read its input. 3136Note 3137that the default standard input for a command run detached is 3138.Em not 3139the empty file 3140.Pa /dev/null , 3141but the original standard input of the shell. 3142If this is a terminal and if the process attempts to read from the terminal, 3143then the process will block and the user will be notified (see 3144.Sx Jobs ) . 3145.Pp 3146Diagnostic output may be directed through a pipe with the standard output. 3147Simply use the form 3148.Ql |& 3149rather than just 3150.Ql | . 3151.Pp 3152The shell cannot presently redirect diagnostic output without also redirecting 3153standard output, but 3154.Ql \&( Ar command Li > Ar output-file Li ) >& Ar error-file 3155is often an acceptable workaround. 3156Either 3157.Ar output-file 3158or 3159.Ar error-file 3160may be 3161.Pa /dev/tty 3162to send output to the terminal. 3163. 3164.Ss "Features" 3165Having described how the shell accepts, parses and executes 3166command lines, we now turn to a variety of its useful features. 3167. 3168.Ss "Control flow" 3169The shell contains a number of commands which can be used to regulate the 3170flow of control in command files (shell scripts) and (in limited but 3171useful ways) from terminal input. 3172These commands all operate by forcing the 3173shell to reread or skip in its input and, due to the implementation, 3174restrict the placement of some of the commands. 3175.Pp 3176The 3177.Ic foreach , 3178.Ic switch , 3179and 3180.Ic while 3181statements, as well as the 3182.Ic if \&... then \&... else 3183form of the 3184.Ic if 3185statement, require that the major 3186keywords appear in a single simple command on an input line as shown below. 3187.Pp 3188If the shell's input is not seekable, the shell buffers up input whenever 3189a loop is being read and performs seeks in this internal buffer to 3190accomplish the rereading implied by the loop. 3191(To the extent that this allows, backward 3192.Ic goto Ns 3193s will succeed on non-seekable inputs.) 3194. 3195.Ss "Expressions" 3196The 3197.Ic if , 3198.Ic while , 3199and 3200.Ic exit 3201builtin commands 3202use expressions with a common syntax. 3203The expressions can include any 3204of the operators described in the next three sections. 3205Note that the 3206.Ic @ 3207builtin command (q.v.) has its own separate syntax. 3208. 3209.Ss "Logical, arithmetical and comparison operators" 3210These operators are similar to those of C and have the same precedence. 3211.Pp 3212The operators, in descending precedence, with equivalent precedence per line, are: 3213.Pp 3214.Bl -column -offset indent -compact "XX" "XX" "XX" "XX" 3215.It Li \&( Ta Li \&) 3216.It Li \&~ 3217.It Li \&! 3218.It Li * Ta Li / Ta Li % 3219.It Li + Ta Li \- 3220.It Li << Ta Li >> 3221.It Li <= Ta Li >= Ta Li < Ta Li > 3222.It Li == Ta Li \&!= Ta Li =~ Ta Li \&!~ 3223.It Li & 3224.It Li ^ 3225.It Li | 3226.It Li && 3227.It Li || 3228.El 3229.Pp 3230The 3231.Ql == 3232.Ql \&!= 3233.Ql =~ 3234and 3235.Ql \&!~ 3236operators compare 3237their arguments as strings; all others operate on numbers. 3238The operators 3239.Ql =~ 3240and 3241.Ql \&!~ 3242are like 3243.Ql == 3244and 3245.Ql \&!= 3246except that the right hand side is a 3247glob-pattern (see 3248.Sx Filename substitution ) 3249against which the left hand operand is matched. 3250This reduces the need for use of the 3251.Ic switch 3252builtin command in shell scripts when all that is really needed is 3253pattern matching. 3254.Pp 3255Null or 3256missing arguments are considered 3257.Ql 0 . 3258The results of all expressions are 3259strings, which represent decimal numbers. 3260It is important to note that 3261no two components of an expression can appear in the same word; except 3262when adjacent to components of expressions which are syntactically 3263significant to the parser 3264.Po 3265.Ql \&& , 3266.Ql | , 3267.Ql < , 3268.Ql > , 3269.Ql \&( , 3270.Ql \&) 3271.Pc 3272they should be 3273surrounded by spaces. 3274. 3275.Ss "Command exit status" 3276Commands can be executed in expressions and their exit status 3277returned by enclosing them in braces 3278.Pq Ql {} . 3279Remember that the braces should 3280be separated from the words of the command by spaces. 3281Command executions 3282succeed, returning true, i.e., 3283.Ql 1 , 3284if the command exits with status 0, 3285otherwise they fail, returning false, i.e., 3286.Ql 0 . 3287If more detailed status 3288information is required then the command should be executed outside of an 3289expression and the 3290.Ic status 3291shell variable examined. 3292. 3293.Ss "File inquiry operators" 3294Some of these operators perform true/false tests on files and related 3295objects. 3296They are of the form 3297.Fl Ar op file , 3298where 3299.Ar op 3300is one of: 3301.Pp 3302.Bl -tag -width 3n -offset indent -compact 3303. 3304.It Li r 3305Read access. 3306. 3307.It Li w 3308Write access. 3309. 3310.It Li x 3311Execute access. 3312. 3313.It Li X 3314Executable in the path or shell builtin, e.g., 3315.Ql \-X ls 3316and 3317.Ql \-X ls\-F 3318are 3319generally true, but 3320.Ql \-X /bin/ls 3321is not. (+) 3322. 3323.It Li e 3324Existence. 3325. 3326.It Li o 3327Ownership. 3328. 3329.It Li z 3330Zero size. 3331. 3332.It Li s 3333Non-zero size. (+) 3334. 3335.It Li f 3336Plain file. 3337. 3338.It Li d 3339Directory. 3340. 3341.It Li l 3342Symbolic link. (+) * 3343. 3344.It Li b 3345Block special file. (+) 3346. 3347.It Li c 3348Character special file. (+) 3349. 3350.It Li p 3351Named pipe (fifo). (+) * 3352. 3353.It Li S 3354Socket special file. (+) * 3355. 3356.It Li u 3357Set-user-ID bit is set. (+) 3358. 3359.It Li g 3360Set-group-ID bit is set. (+) 3361. 3362.It Li k 3363Sticky bit is set. (+) 3364. 3365.It Li t 3366.Ar file 3367(which must be a digit) is an open file descriptor 3368for a terminal device. (+) 3369. 3370.It Li R 3371Has been migrated (Convex only). (+) 3372. 3373.It Li L 3374Applies subsequent operators in a multiple-operator test to a symbolic link 3375rather than to the file to which the link points. (+) * 3376.El 3377.Pp 3378.Ar file 3379is command and filename expanded and then tested to 3380see if it has the specified relationship to the real user. 3381If 3382.Ar file 3383does not exist or is inaccessible or, for the operators indicated by 3384.Sq * , 3385if the specified file type does not exist on the current system, 3386then all inquiries return false, i.e., 3387.Ql 0 . 3388.Pp 3389These operators may be combined for conciseness: 3390.Ql \- Ns Ar xy file 3391is 3392equivalent to 3393.Ql \- Ns Ar x file Li && \- Ns Ar y file . 3394(+) For example, 3395.Ql \-fx 3396is true 3397(returns 3398.Ql 1 ) 3399for plain executable files, but not for directories. 3400.Pp 3401.Ql L 3402may be used in a multiple-operator test to apply subsequent operators 3403to a symbolic link rather than to the file to which the link points. 3404For example, 3405.Ql \-lLo 3406is true for links owned by the invoking user. 3407.Ql Lr , 3408.Ql Lw , 3409and 3410.Ql Lx 3411are always true for links and false for 3412non-links. 3413.Ql L 3414has a different meaning when it is the last operator 3415in a multiple-operator test; see below. 3416.Pp 3417It is possible but not useful, and sometimes misleading, to combine operators 3418which expect 3419.Ar file 3420to be a file with operators which do not 3421(e.g., 3422.Ql X 3423and 3424.Ql t ) . 3425Following 3426.Ql L 3427with a non-file operator 3428can lead to particularly strange results. 3429.Pp 3430Other operators return other information, i.e., not just 3431.Ql 0 3432or 3433.Ql 1 . 3434(+) 3435They have the same format as before; 3436.Ar op 3437may be one of: 3438.Pp 3439.Bl -tag -width 6n -offset indent -compact 3440. 3441.It Li A 3442Last file access time, as the number of seconds since the epoch. 3443. 3444.It Li A: 3445Like 3446.Ql A , 3447but in timestamp format, e.g., 3448.Sq Fri May 14 16:36:10 1993 . 3449. 3450.It Li M 3451Last file modification time. 3452. 3453.It Li M: 3454Like 3455.Ql M , 3456but in timestamp format. 3457. 3458.It Li C 3459Last inode modification time. 3460. 3461.It Li C: 3462Like 3463.Ql C , 3464but in timestamp format. 3465. 3466.It Li D 3467Device number. 3468. 3469.It Li I 3470Inode number. 3471. 3472.It Li F 3473Composite 3474.Li f Ns 3475ile identifier, in the form 3476.Ar device : Ns 3477.Ar inode . 3478. 3479.It Li L 3480The name of the file pointed to by a symbolic link. 3481. 3482.It Li N 3483Number of (hard) links. 3484. 3485.It Li P 3486Permissions, in octal, without leading zero. 3487. 3488.It Li P: 3489Like 3490.Ql P , 3491with leading zero. 3492. 3493.It Li P Ns Ar mode 3494Equivalent to 3495.Ql \-P Ar file Li & Ar mode , 3496e.g., 3497.Ql \-P22 Ar file 3498returns 3499.Sq 22 3500if 3501.Ar file 3502is writable by group and other, 3503.Sq 20 3504if by group only, 3505and 3506.Sq 0 3507if by neither. 3508. 3509.It Li P Ns Ar mode Ns Li \&: 3510Like 3511.Ql P Ns Ar mode , 3512with leading zero. 3513. 3514.It Li U 3515Numeric userid. 3516. 3517.It Li U: 3518Username, or the numeric userid if the username is unknown. 3519. 3520.It Li G 3521Numeric groupid. 3522. 3523.It Li G: 3524Groupname, or the numeric groupid if the groupname is unknown. 3525. 3526.It Li Z 3527Size, in bytes. 3528.El 3529.Pp 3530Only one of these operators may appear in a multiple-operator test, and it 3531must be the last. 3532Note that 3533.Ql L 3534has a different meaning at the end of and 3535elsewhere in a multiple-operator test. 3536Because 3537.Sq 0 3538is a valid return value 3539for many of these operators, they do not return 3540.Sq 0 3541when they fail: most 3542return 3543.Sq \-1 , 3544and 3545.Ql F 3546returns 3547.Ql \&: . 3548.Pp 3549If the shell is compiled with POSIX defined (see the 3550.Ic version 3551shell 3552variable), the result of a file inquiry is based on the permission bits of 3553the file and not on the result of the 3554.Xr access 2 3555system call. 3556For example, if one tests a file with 3557.Fl w 3558whose permissions would 3559ordinarily allow writing but which is on a file system mounted read-only, 3560the test will succeed in a POSIX shell but fail in a non-POSIX shell. 3561.Pp 3562File inquiry operators can also be evaluated with the 3563.Ic filetest 3564builtin 3565command (q.v.) (+). 3566. 3567.Ss Jobs 3568The shell associates a 3569.Ar job 3570with each pipeline. 3571It keeps a table of 3572current jobs, printed by the 3573.Ic jobs 3574command, and assigns them small integer 3575numbers. 3576When a job is started asynchronously with 3577.Ql & , 3578the shell prints a 3579line which looks like 3580.Bd -literal -offset indent 3581[1] 1234 3582.Ed 3583.Pp 3584indicating that the job which was started asynchronously was job number 1 and 3585had one (top-level) process, whose process id was 1234. 3586.Pp 3587If you are running a job and wish to do something else you may hit the suspend 3588key (usually 3589.Sq ^Z ) , 3590which sends a STOP signal to the current job. 3591The shell will then normally 3592indicate that the job has been 3593.Sq Suspended 3594and print another prompt. 3595If the 3596.Ic listjobs 3597shell variable is set, all jobs will be listed 3598like the 3599.Ic jobs 3600builtin command; if it is set to 3601.Ql long 3602the listing will 3603be in long format, like 3604.Ql jobs \-l . 3605You can then manipulate the state of the suspended job. 3606You can put it in the 3607.Dq background 3608with the 3609.Ic bg 3610command or run some other commands and 3611eventually bring the job back into the 3612.Dq foreground 3613with 3614.Ic fg . 3615(See also the 3616.Ic run-fg-editor 3617editor command.) 3618A 3619.Sq ^Z 3620takes effect immediately and is like an interrupt 3621in that pending output and unread input are discarded when it is typed. 3622The 3623.Ic wait 3624builtin command causes the shell to wait for all background 3625jobs to complete. 3626.Pp 3627The 3628.Sq ^] 3629key sends a delayed suspend signal, which does not generate a STOP 3630signal until a program attempts to 3631.Xr read 2 3632it, to the current job. 3633This can usefully be typed ahead when you have prepared some commands for a 3634job which you wish to stop after it has read them. 3635The 3636.Sq ^Y 3637key performs this function in 3638.Xr csh 1 ; 3639in 3640.Nm , 3641.Sq ^Y 3642is an editing command. 3643(+) 3644.Pp 3645A job being run in the background stops if it tries to read from the 3646terminal. 3647Background jobs are normally allowed to produce output, but this can 3648be disabled by giving the command 3649.Ql stty tostop . 3650If you set this tty option, 3651then background jobs will stop when they try to produce output like they do 3652when they try to read input. 3653.Pp 3654There are several ways to refer to jobs in the shell. 3655The character 3656.Ql % 3657introduces a job name. 3658If you wish to refer to job number 1, you can name it 3659as 3660.Ql %1 . 3661Just naming a job brings it to the foreground; thus 3662.Ql %1 3663is a synonym 3664for 3665.Ql fg %1 , 3666bringing job 1 back into the foreground. 3667Similarly, typing 3668.Ql %1 & 3669resumes job 1 in the background, just like 3670.Ql bg %1 . 3671A job can also be named 3672by an unambiguous prefix of the string typed in to start it: 3673.Ql %ex 3674would 3675normally restart a suspended 3676.Xr ex 1 3677job, if there were only one suspended 3678job whose name began with the string 3679.Ql ex . 3680It is also possible to type 3681.Ql %? Ns Ar string 3682to specify a job whose text contains 3683.Ar string , 3684if there is only one such job. 3685.Pp 3686The shell maintains a notion of the current and previous jobs. 3687In output 3688pertaining to jobs, the current job is marked with a 3689.Ql + 3690and the previous job 3691with a 3692.Ql \- . 3693The abbreviations 3694.Ql %+ , 3695.Ql % , 3696and (by analogy with the syntax of 3697the 3698.Ic history 3699mechanism) 3700.Ql %% 3701all refer to the current job, and 3702.Ql %\- 3703refers 3704to the previous job. 3705.Pp 3706The job control mechanism requires that the 3707.Xr stty 1 3708option 3709.Ql new 3710be set 3711on some systems. 3712It is an artifact from a 3713.Dq new 3714implementation of the tty 3715driver which allows generation of interrupt characters from the keyboard to 3716tell jobs to stop. 3717See 3718.Xr stty 1 3719and the 3720.Ic setty 3721builtin command for 3722details on setting options in the new tty driver. 3723. 3724.Ss "Status reporting" 3725The shell learns immediately whenever a process changes state. 3726It normally 3727informs you whenever a job becomes blocked so that no further progress is 3728possible, but only right before it prints a prompt. 3729This is done so that it 3730does not otherwise disturb your work. 3731If, however, you set the shell variable 3732.Ic notify , 3733the shell will notify you immediately of changes of status in 3734background jobs. 3735There is also a builtin command 3736.Ic notify 3737which marks a 3738single process so that its status changes will be immediately reported. 3739By 3740default 3741.Ic notify 3742marks the current process; simply enter 3743.Ql notify 3744after 3745starting a background job to mark it. 3746.Pp 3747When you try to leave the shell while jobs are stopped, you will be 3748warned that 3749.Sq There are suspended jobs. 3750You may use the 3751.Ic jobs 3752command to 3753see what they are. 3754If you do this or immediately try to exit again, the shell 3755will not warn you a second time, and the suspended jobs will be terminated. 3756. 3757.Ss "Automatic, periodic and timed events (+)" 3758There are various ways to run commands and take other actions automatically 3759at various times in the 3760.Dq life cycle 3761of the shell. 3762They are summarized here, 3763and described in detail under the appropriate 3764.Sx Builtin commands , 3765.Sx Special shell variables , 3766and 3767.Sx Special aliases . 3768.Pp 3769The 3770.Ic sched 3771builtin command puts commands in a scheduled-event list, 3772to be executed by the shell at a given time. 3773.Pp 3774The 3775.Ic beepcmd , 3776.Ic cwdcmd , 3777.Ic jobcmd , 3778.Ic periodic , 3779.Ic precmd , 3780and 3781.Ic postcmd 3782.Sx Special aliases 3783can be set, respectively, to execute commands: 3784when the shell wants to ring the bell, 3785when the working directory changes, 3786when a job is started or is brought into the foreground, 3787every 3788.Ic tperiod 3789minutes, 3790before each prompt, 3791and before each command gets executed. 3792.Pp 3793The 3794.Ic autologout 3795shell variable can be set to log out or lock the shell 3796after a given number of minutes of inactivity. 3797.Pp 3798The 3799.Ic mail 3800shell variable can be set to check for new mail periodically. 3801.Pp 3802The 3803.Ic printexitvalue 3804shell variable can be set to print the exit status 3805of commands which exit with a status other than zero. 3806.Pp 3807The 3808.Ic rmstar 3809shell variable can be set to ask the user, when 3810.Ql rm * 3811is 3812typed, if that is really what was meant. 3813.Pp 3814The 3815.Ic time 3816shell variable can be set to execute the 3817.Ic time 3818builtin 3819command after the completion of any process that takes more than a given 3820number of CPU seconds. 3821.Pp 3822The 3823.Ic watch 3824and 3825.Ic who 3826shell variables can be set to report when 3827selected users log in or out, and the 3828.Ic log 3829builtin command reports 3830on those users at any time. 3831. 3832.Ss "Native Language System support (+)" 3833The shell is eight bit clean 3834(if so compiled; see the 3835.Ic version 3836shell variable) 3837and thus supports character sets needing this capability. 3838NLS support differs depending on whether or not 3839the shell was compiled to use the system's NLS (again, see 3840.Ic version ) . 3841In either case, 7-bit ASCII is the default character code 3842(e.g., the classification of which characters are printable) and sorting, 3843and changing the 3844.Ev LANG 3845or 3846.Ev LC_CTYPE 3847environment variables 3848causes a check for possible changes in these respects. 3849.Pp 3850When using the system's NLS, the 3851.Xr setlocale 3 3852function is called 3853to determine appropriate character code/classification and sorting 3854(e.g., 3855.Sq en_CA.UTF-8 3856would yield 3857.Sq UTF-8 3858as the character code). 3859This function typically examines the 3860.Ev LANG 3861and 3862.Ev LC_CTYPE 3863environment variables; refer to the system documentation for further details. 3864When not using the system's NLS, the shell simulates it by assuming that the 3865ISO 8859-1 character set is used 3866whenever either of the 3867.Ev LANG 3868and 3869.Ev LC_CTYPE 3870variables are set, regardless of 3871their values. 3872Sorting is not affected for the simulated NLS. 3873.Pp 3874In addition, with both real and simulated NLS, all printable 3875characters in the range \e200\-\e377, i.e., those that have 3876.No M- Ns Ar char 3877bindings, are automatically rebound to 3878.Ic self-insert-command . 3879The corresponding binding for the 3880.No escape- Ns Ar char 3881sequence, if any, is 3882left alone. 3883These characters are not rebound if the 3884.Ev NOREBIND 3885environment variable 3886is set. 3887This may be useful for the simulated NLS or a primitive real NLS 3888which assumes full ISO 8859-1. 3889Otherwise, all 3890.No M- Ns Ar char 3891bindings in the 3892range \e240\-\e377 are effectively undone. 3893Explicitly rebinding the relevant keys with 3894.Ic bindkey 3895is of course still possible. 3896.Pp 3897Unknown characters (i.e., those that are neither printable nor control 3898characters) are printed in the format \ennn. 3899If the tty is not in 8 bit mode, other 8 bit characters are printed by 3900converting them to ASCII and using standout mode. 3901The shell 3902never changes the 7/8 bit mode of the tty and tracks user-initiated 3903changes of 7/8 bit mode. 3904NLS users (or, for that matter, those who want to 3905use a meta key) may need to explicitly set 3906the tty in 8 bit mode through the appropriate 3907.Xr stty 1 3908command in, e.g., the 3909.Pa ~/.login 3910file. 3911. 3912.Ss "OS variant support (+)" 3913A number of new builtin commands are provided to support features in 3914particular operating systems. 3915All are described in detail in the 3916.Sx Builtin commands 3917section. 3918.Pp 3919On systems that support TCF (aix-ibm370, aix-ps2), 3920.Ic getspath 3921and 3922.Ic setspath 3923get and set the system execution path, 3924.Ic getxvers 3925and 3926.Ic setxvers 3927get and set the experimental version prefix 3928and 3929.Ic migrate 3930migrates processes between sites. 3931The 3932.Ic jobs 3933builtin 3934prints the site on which each job is executing. 3935.Pp 3936Under BS2000, 3937.Ic bs2cmd 3938executes commands of the underlying BS2000/OSD 3939operating system. 3940.Pp 3941Under Domain/OS, 3942.Ic inlib 3943adds shared libraries to the current environment, 3944.Ic rootnode 3945changes the rootnode and 3946.Ic ver 3947changes the systype. 3948.Pp 3949Under Mach, 3950.Ic setpath 3951is equivalent to Mach's 3952.Xr setpath 1 . 3953.Pp 3954Under Masscomp/RTU and Harris CX/UX, 3955.Ic universe 3956sets the universe. 3957.Pp 3958Under Harris CX/UX, 3959.Ic ucb 3960or 3961.Ic att 3962runs a command under the specified 3963universe. 3964.Pp 3965Under Convex/OS, 3966.Ic warp 3967prints or sets the universe. 3968.Pp 3969The 3970.Ev VENDOR , 3971.Ev OSTYPE , 3972and 3973.Ev MACHTYPE 3974environment variables 3975indicate respectively the vendor, operating system and machine type 3976(microprocessor class or machine model) of the 3977system on which the shell thinks it is running. 3978These are particularly useful when sharing one's home directory between several 3979types of machines; one can, for example, 3980.Bd -literal -offset indent 3981set path = (~/bin.$MACHTYPE /usr/ucb /bin /usr/bin .) 3982.Ed 3983.Pp 3984in one's 3985.Pa ~/.login 3986and put executables compiled for each machine in the 3987appropriate directory. 3988.Pp 3989The 3990.Ic version 3991shell 3992variable indicates what options were chosen when the shell was compiled. 3993.Pp 3994Note also the 3995.Ic newgrp 3996builtin, the 3997.Ic afsuser 3998and 3999.Ic echo_style 4000shell variables and the system-dependent locations of 4001the shell's input files (see 4002.Sx FILES ) . 4003. 4004.Ss "Signal handling" 4005Login shells ignore interrupts when reading the file 4006.Pa ~/.logout . 4007The shell ignores quit signals unless started with 4008.Fl q . 4009Login shells catch the terminate signal, but non-login shells inherit the 4010terminate behavior from their parents. 4011Other signals have the values which the shell inherited from its parent. 4012.Pp 4013In shell scripts, the shell's handling of interrupt and terminate signals 4014can be controlled with 4015.Ic onintr , 4016and its handling of hangups can be 4017controlled with 4018.Ic hup 4019and 4020.Ic nohup . 4021.Pp 4022The shell exits on a hangup (see also the 4023.Ic logout 4024shell variable). 4025By 4026default, the shell's children do too, but the shell does not send them a 4027hangup when it exits. 4028.Ic hup 4029arranges for the shell to send a hangup to 4030a child when it exits, and 4031.Ic nohup 4032sets a child to ignore hangups. 4033. 4034.Ss "Terminal management (+)" 4035The shell uses three different sets of terminal 4036.Dq ( tty ) 4037modes: 4038.Sq edit , 4039used when editing; 4040.Sq quote , 4041used when quoting literal characters; 4042and 4043.Sq execute , 4044used when executing commands. 4045The shell holds some settings in each mode constant, so commands which leave 4046the tty in a confused state do not interfere with the shell. 4047The shell also matches changes in the speed and padding of the tty. 4048The list of tty modes that are kept constant 4049can be examined and modified with the 4050.Ic setty 4051builtin. 4052Note that although the editor uses CBREAK mode (or its equivalent), 4053it takes typed-ahead characters anyway. 4054.Pp 4055The 4056.Ic echotc , 4057.Ic settc , 4058and 4059.Ic telltc 4060commands can be used to 4061manipulate and debug terminal capabilities from the command line. 4062.Pp 4063On systems that support SIGWINCH or SIGWINDOW, the shell 4064adapts to window resizing automatically and adjusts the environment 4065variables 4066.Ev LINES 4067and 4068.Ev COLUMNS 4069if set. 4070If the environment 4071variable 4072.Ev TERMCAP 4073contains 4074.Ql li# 4075and 4076.Ql co# 4077fields, the shell adjusts 4078them to reflect the new window size. 4079. 4080.Sh REFERENCE 4081The next sections of this manual describe all of the available 4082.Sx Builtin commands , 4083.Sx Special aliases , 4084and 4085.Sx Special shell variables . 4086. 4087.Ss "Builtin commands" 4088. 4089.Bl -tag -width 8n 4090. 4091.It Ic % Ns Ar job 4092A synonym for the 4093.Ic fg 4094builtin command. 4095. 4096.It Ic % Ns Ar job Cm \&& 4097A synonym for the 4098.Ic bg 4099builtin command. 4100. 4101.It Ic \&: 4102Does nothing, successfully. 4103. 4104.El 4105.Pp 4106.Bl -tag -width 8n -compact 4107. 4108.It Ic @ 4109.It Ic @ Ar name Cm = Ar expr 4110.It Ic @ Ar name Ns Cm \&[ Ns Ar index Ns Cm \&] = Ar expr 4111.It Ic @ Ar name Ns Cm ++|-- 4112.It Ic @ Ar name Ns Cm \&[ Ns Ar index Ns Cm \&]++|-- 4113The first form prints the values of all shell variables. 4114.Pp 4115The second form assigns the value of 4116.Ar expr 4117to 4118.Ar name . 4119.Pp 4120The third form assigns the value of 4121.Ar expr 4122to the 4123.Ar index Ns 4124\&'th 4125component of 4126.Ar name ; 4127both 4128.Ar name 4129and its 4130.Ar index Ns 4131\&'th component 4132must already exist. 4133.Pp 4134.Ar expr 4135may contain the operators 4136.Ql * , 4137.Ql + , 4138etc., as in C. 4139If 4140.Ar expr 4141contains 4142.Ql < , 4143.Ql > , 4144.Ql & , 4145or 4146.Ql \&| 4147then at least that part of 4148.Ar expr 4149must be placed within 4150.Ql () . 4151Note that the syntax of 4152.Ar expr 4153has nothing to do with that described 4154under 4155.Sx Expressions . 4156.Pp 4157The fourth and fifth forms increment 4158.Pq Sq Cm ++ 4159or decrement 4160.Pq Sq Cm -- 4161.Ar name 4162or its 4163.Ar index Ns 4164\&'th component. 4165.Pp 4166The space between 4167.Sq Ic @ 4168and 4169.Ar name 4170is required. 4171The spaces between 4172.Ar name 4173and 4174.Sq Cm = 4175and between 4176.Sq Cm = 4177and 4178.Ar expr 4179are optional. 4180Components of 4181.Ar expr 4182must be separated by spaces. 4183. 4184.El 4185.Bl -tag -width 8n 4186. 4187.It Ic alias Op Ar name Op Ar wordlist 4188Without arguments, prints all aliases. 4189With 4190.Ar name , 4191prints the alias for name. 4192With 4193.Ar name 4194and 4195.Ar wordlist , 4196assigns 4197.Ar wordlist 4198as the alias of 4199.Ar name . 4200.Ar wordlist 4201is command and filename substituted. 4202.Ar name 4203may not be 4204.Sq Ic alias 4205or 4206.Sq Ic unalias . 4207See also the 4208.Ic unalias 4209builtin command. 4210. 4211.It Ic alloc 4212Shows the amount of dynamic memory acquired, broken down into used and free 4213memory. 4214With an argument shows the number of free and used blocks in each size 4215category. 4216The categories start at size 8 and double at each step. 4217This command's output may vary across system types, because systems other 4218than the VAX may use a different memory allocator. 4219. 4220.It Ic bg Op Cm % Ns Ar job No \&... 4221Puts the specified jobs (or, without arguments, the current job) 4222into the background, continuing each if it is stopped. 4223.Ar job 4224may be a number, a string, 4225.Ql \& , 4226.Ql % , 4227.Ql + , 4228or 4229.Ql \- 4230as described under 4231.Sx Jobs . 4232. 4233.El 4234.Pp 4235.Bl -tag -width 8n -compact 4236. 4237.It Ic bindkey Oo Fl l Ns | Ns Fl d Ns | Ns Fl e Ns | Ns Fl v Ns | Ns Fl u Oc No (+) 4238.It Ic bindkey Oo Fl a Oc Oo Fl b Oc Oo Fl k Oc Oo Fl r Oc Oo Fl \- Oc Ar key No (+) 4239.It Ic bindkey Oo Fl a Oc Oo Fl b Oc Oo Fl k Oc Oo Fl c Ns | Ns Fl s Oc Oo Fl \- Oc Ar key command No (+) 4240The first form either lists all bound keys and the editor 4241command to which each is bound, 4242lists a description of the commands, 4243or binds all keys to a specific mode. 4244.Pp 4245The second form lists the editor command to which 4246.Ar key 4247is bound. 4248.Pp 4249The third form binds the editor command 4250.Ar command 4251to 4252.Ar key . 4253.Pp 4254Supported 4255.Ic bindkey 4256options: 4257.Pp 4258.Bl -tag -width 5n -offset indent -compact 4259. 4260.It Fl a 4261Lists or changes key-bindings in the alternative key map. 4262This is the key map used in 4263.Ic vimode 4264command mode. 4265. 4266.It Fl b 4267.Ar key 4268is interpreted as 4269a control character written 4270.No ^ Ns Ar character 4271(e.g., 4272.Sq ^A ) 4273or 4274.No C- Ns Ar character 4275(e.g., 4276.Sq C-A ) , 4277a meta character written 4278.No M- Ns Ar character 4279(e.g., 4280.Sq M-A ) , 4281a function key written 4282.No F- Ns Ar string 4283(e.g., 4284.Sq F-string ) , 4285or an extended prefix key written 4286.No X- Ns Ar character 4287(e.g., 4288.Sq X-A ) . 4289. 4290.It Fl c 4291.Ar command 4292is interpreted as a builtin or external command instead of an 4293editor command. 4294. 4295.It Fl d 4296Binds all keys to the standard bindings for the default editor, 4297as per 4298.Fl e 4299and 4300.Fl v . 4301. 4302.It Fl e 4303Binds all keys to 4304.Xr emacs 1 Ns 4305\-style bindings. 4306Unsets 4307.Ic vimode . 4308. 4309.It Fl k 4310.Ar key 4311is interpreted as a symbolic arrow key name, which may be one of 4312.Sq down , 4313.Sq up , 4314.Sq left , 4315or 4316.Sq right . 4317. 4318.It Fl l 4319Lists all editor commands and a short description of each. 4320. 4321.It Fl r 4322Removes 4323.Ar key Ns 4324\&'s binding. 4325Be careful: 4326.Ql bindkey \-r 4327does 4328.Em not 4329bind 4330.Ar key 4331to 4332.Ic self-insert-command 4333(q.v.), it unbinds 4334.Ar key 4335completely. 4336. 4337.It Fl s 4338.Ar command 4339is taken as a literal string and treated as terminal input when 4340.Ar key 4341is typed. 4342Bound keys in 4343.Ar command 4344are themselves 4345reinterpreted, and this continues for ten levels of interpretation. 4346. 4347.It Fl u No (or any invalid option) 4348Prints a usage message. 4349. 4350.It Fl v 4351Binds all keys to 4352.Xr vi 1 Ns 4353\-style bindings. 4354Sets 4355.Ic vimode . 4356. 4357.It Fl \- 4358Forces a break from option processing, so the next word is taken as 4359.Ar key 4360even if it begins with 4361.Ql \- . 4362. 4363.El 4364.Pp 4365.Ar key 4366may be a single character or a string. 4367If a command is bound to a string, the first character of the string is bound to 4368.Ic sequence-lead-in 4369and the entire string is bound to the command. 4370.Pp 4371Control characters in 4372.Ar key 4373can be literal (they can be typed by preceding 4374them with the editor command 4375.Ic quoted-insert , 4376normally bound to 4377.Sq ^V ) 4378or 4379written caret-character style, e.g., 4380.Sq ^A . 4381Delete is written 4382.Sq ^? 4383(caret-question mark). 4384.Ar key 4385and 4386.Ar command 4387can contain backslashed 4388escape sequences (in the style of System V 4389.Xr echo 1 ) 4390as follows: 4391.Pp 4392.Bl -tag -width 5n -offset indent -compact 4393. 4394.It Li \ea 4395Bell. 4396.It Li \eb 4397Backspace. 4398.It Li \ee 4399Escape. 4400.It Li \ef 4401Form feed. 4402.It Li \en 4403Newline. 4404.It Li \er 4405Carriage return. 4406.It Li \et 4407Horizontal tab. 4408.It Li \ev 4409Vertical tab. 4410.It Li \e Ns Ar nnn 4411The ASCII character corresponding to the octal number 4412.Ar nnn . 4413.El 4414.Pp 4415.Ql \e 4416nullifies the special meaning of the following character, if it has 4417any, notably 4418.Ql \e 4419and 4420.Ql ^ . 4421. 4422.El 4423.Bl -tag -width 8n 4424. 4425.It Ic bs2cmd Ar bs2000-command No (+) 4426Passes 4427.Ar bs2000-command 4428to the BS2000 command interpreter for 4429execution. Only non-interactive commands can be executed, and it is 4430not possible to execute any command that would overlay the image 4431of the current process, like /EXECUTE or /CALL-PROCEDURE. (BS2000 only) 4432. 4433.It Ic break 4434Causes execution to resume after the 4435.Ic end 4436of the nearest 4437enclosing 4438.Ic foreach 4439or 4440.Ic while . 4441The remaining commands on the 4442current line are executed. 4443Multi-level breaks are thus 4444possible by writing them all on one line. 4445. 4446.It Ic breaksw 4447Causes a break from a 4448.Ic switch , 4449resuming after the 4450.Ic endsw . 4451. 4452.It Ic builtins No (+) 4453Prints the names of all builtin commands. 4454. 4455.It Ic bye No (+) 4456A synonym for the 4457.Ic logout 4458builtin command. 4459Available only if the shell was so compiled; 4460see the 4461.Ic version 4462shell variable. 4463. 4464.It Ic case Ar label Ns Cm : 4465A label in a 4466.Ic switch 4467statement as discussed below. 4468. 4469.It Ic cd Xo 4470.Op Fl p 4471.Op Fl l 4472.Op Fl n Ns | Ns Fl v 4473.Op Fl \- 4474.Op Ar name 4475.Xc 4476If a directory 4477.Ar name 4478is given, changes the shell's working directory 4479to 4480.Ar name . 4481If not, changes to 4482.Ic home , 4483unless the 4484.Ic cdtohome 4485variable is not set, in which case a 4486.Ar name 4487is required. 4488If 4489.Ar name 4490is 4491.Ql \- 4492it is interpreted as the previous working directory 4493(see 4494.Sx Other substitutions ) . 4495(+) 4496If 4497.Ar name 4498is not a subdirectory of the current directory 4499(and does not begin with 4500.Ql / , 4501.Ql ./ 4502or 4503.Ql ../ ) , 4504each component of the variable 4505.Ic cdpath 4506is checked to see if it has a subdirectory 4507.Ar name . 4508Finally, if 4509all else fails but 4510.Ar name 4511is a shell variable whose value 4512begins with 4513.Ql / 4514or 4515.Ql \&. , 4516then this is tried to see if it is a directory, and the 4517.Fl p 4518option is implied. 4519.Pp 4520With 4521.Fl p , 4522prints the final directory stack, just like 4523.Ic dirs . 4524The 4525.Fl l , 4526.Fl n , 4527and 4528.Fl v 4529flags have the same effect on 4530.Ic cd 4531as on 4532.Ic dirs , 4533and they imply 4534.Fl p . 4535(+) 4536Using 4537.Fl \- 4538forces a break from option processing so the next word 4539is taken as the directory 4540.Ar name 4541even if it begins with 4542.Ql \- . 4543(+) 4544.Pp 4545See also the 4546.Ic implicitcd 4547and 4548.Ic cdtohome 4549shell variables. 4550. 4551.It Ic chdir 4552A synonym for the 4553.Ic cd 4554builtin command. 4555. 4556.It Ic complete Xo 4557.Oo Ar command 4558.Oo 4559.Sm off 4560.Ar word Cm / Ar pattern Cm / Ar list Oo Cm : Ar select Oc Cm / Oo 4561.Op Ar suffix 4562.Cm / 4563.Oc 4564.Sm on 4565\&... 4566.Oc 4567.Oc 4568(+) 4569.Xc 4570Without arguments, lists all completions. 4571With 4572.Ar command , 4573lists completions for 4574.Ar command . 4575With 4576.Ar command 4577and 4578.Ar word 4579etc., defines completions. 4580.Pp 4581.Ar command 4582may be a full command name or a glob-pattern 4583(see 4584.Sx Filename substitution ) . 4585It can begin with 4586.Ql \- 4587to indicate that 4588completion should be used only when 4589.Ic command 4590is ambiguous. 4591.Pp 4592.Ar word 4593specifies which word relative to the current word 4594is to be completed, and may be one of the following: 4595.Pp 4596.Bl -tag -width 5n -offset indent -compact 4597. 4598.It Li c 4599Current-word completion. 4600.Ar pattern 4601is a glob-pattern which must match the beginning of the current word on 4602the command line. 4603.Ar pattern 4604is ignored when completing the current word. 4605. 4606.It Li C 4607Like 4608.Ql c , 4609but includes 4610.Ar pattern 4611when completing the current word. 4612. 4613.It Li n 4614Next-word completion. 4615.Ar pattern 4616is a glob-pattern which must match the beginning of the previous word on 4617the command line. 4618. 4619.It Li N 4620Like 4621.Ql n , 4622but must match the beginning of the word two before the current word. 4623. 4624.It Li p 4625Position-dependent completion. 4626.Ar pattern 4627is a numeric range, with the same syntax used to index shell 4628variables, which must include the current word. 4629.El 4630.Pp 4631.Ar list , 4632the list of possible completions, may be one of the following: 4633.Pp 4634.Bl -tag -width 5n -offset indent -compact 4635. 4636.It Li a 4637Aliases. 4638. 4639.It Li b 4640Bindings (editor commands). 4641. 4642.It Li c 4643Commands (builtin or external commands). 4644. 4645.It Li C 4646External commands which begin with the supplied path prefix. 4647. 4648.It Li d 4649Directories. 4650. 4651.It Li D 4652Directories which begin with the supplied path prefix. 4653. 4654.It Li e 4655Environment variables. 4656. 4657.It Li f 4658Filenames. 4659. 4660.It Li F 4661Filenames which begin with the supplied path prefix. 4662. 4663.It Li g 4664Groupnames. 4665. 4666.It Li j 4667Jobs. 4668. 4669.It Li l 4670Limits. 4671. 4672.It Li n 4673Nothing. 4674. 4675.It Li s 4676Shell variables. 4677. 4678.It Li S 4679Signals. 4680. 4681.It Li t 4682Plain 4683.Dq ( text ) 4684files. 4685. 4686.It Li T 4687Plain 4688.Dq ( text ) 4689files which begin with the supplied path prefix. 4690. 4691.It Li v 4692Any variables. 4693. 4694.It Li u 4695Usernames. 4696. 4697.It Li x 4698Like 4699.Ql n , 4700but prints 4701.Ar select 4702when 4703.Ic list-choices 4704is used. 4705. 4706.It Li X 4707Completions. 4708. 4709.It Li $ Ns Ar var 4710Words from the variable 4711.Ar var . 4712. 4713.It Li (...) 4714Words from the given list. 4715. 4716.It Li \`...\` 4717Words from the output of command. 4718.El 4719.Pp 4720.Ar select 4721is an optional glob-pattern. 4722If given, words from only 4723.Ar list 4724that match 4725.Ar select 4726are considered 4727and the 4728.Ic fignore 4729shell variable is ignored. 4730The 4731.Ar list 4732types 4733.Ql $ Ns Ar var , 4734.Ql (...) , 4735and 4736.Ql \`...\` 4737may not have a 4738.Ar select 4739pattern, and 4740.Ql x 4741uses 4742.Ar select 4743as an explanatory message when the 4744.Ic list-choices 4745editor command is used. 4746.Pp 4747.Ar suffix 4748is a single character to be appended to a successful 4749completion. 4750If null, no character is appended. 4751If omitted (in which 4752case the fourth delimiter can also be omitted), a slash is appended to 4753directories and a space to other words. 4754.Pp 4755.Ar command 4756invoked from 4757.Ar list 4758.Ql \`...\` 4759has the additional environment variable 4760.Ev COMMAND_LINE 4761set, which 4762contains (as its name indicates) contents of the current (already 4763typed in) command line. One can examine and use contents of the 4764.Ev COMMAND_LINE 4765environment variable in a custom script to build more 4766sophisticated completions (see completion for 4767.Xr svn 1 4768included in this package). 4769.Pp 4770Now for some examples. 4771Some commands take only directories as arguments, 4772so there's no point completing plain files. 4773.Bd -literal -offset indent 4774> complete cd 'p/1/d/' 4775.Ed 4776.Pp 4777completes only the first word following 4778.Ql cd 4779.Pq Ql p/1 4780with a directory. 4781.Ql p Ns 4782\-type completion can also be used to narrow down command completion: 4783.Bd -literal -offset indent 4784> co[^D] 4785complete compress 4786> complete \-co* 'p/0/(compress)/' 4787> co[^D] 4788> compress 4789.Ed 4790.Pp 4791This completion completes commands (words in position 0, 4792.Ql p/0 ) 4793which begin with 4794.Ql co 4795(thus matching 4796.Ql co* ) 4797to 4798.Ql compress 4799(the only 4800word in the list). 4801The leading 4802.Ql \- 4803indicates that this completion is to be used with only 4804ambiguous commands. 4805.Bd -literal -offset indent 4806> complete find 'n/\-user/u/' 4807.Ed 4808.Pp 4809is an example of 4810.Ql n Ns 4811\-type completion. 4812Any word following 4813.Ql find 4814and 4815immediately following 4816.Ql \-user 4817is completed from the list of users. 4818.Bd -literal -offset indent 4819> complete cc 'c/\-I/d/' 4820.Ed 4821.Pp 4822demonstrates 4823.Ql c Ns 4824\-type completion. 4825Any word following 4826.Ql cc 4827and beginning with 4828.Ql \-I 4829is completed as a directory. 4830.Ql \-I 4831is not taken as part of the 4832directory because we used lowercase 4833.Ql c . 4834.Pp 4835Different 4836.Ar list Ns No s 4837are useful with different commands. 4838.Bd -literal -offset indent 4839> complete alias 'p/1/a/' 4840> complete man 'p/*/c/' 4841> complete set 'p/1/s/' 4842> complete true 'p/1/x:Truth has no options./' 4843.Ed 4844.Pp 4845These complete words following 4846.Ql alias 4847with aliases, 4848.Ql man 4849with commands, 4850and 4851.Ql set 4852with shell variables. 4853.Ic true 4854doesn't have any options, so 4855.Ql x 4856does nothing when completion 4857is attempted and prints 4858.Sq Truth has no options. 4859when completion choices are listed. 4860.Pp 4861Note that the 4862.Ql man 4863example, and several other examples below, could 4864just as well have used 4865.Ql 'c/*' 4866or 4867.Ql 'n/*' 4868as 4869.Ql 'p/*' . 4870.Pp 4871Words can be completed from a variable evaluated at completion time, 4872.Bd -literal -offset indent 4873> complete ftp 'p/1/$hostnames/' 4874> set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu) 4875> ftp [^D] 4876rtfm.mit.edu tesla.ee.cornell.edu 4877> ftp [^C] 4878> set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net) 4879> ftp [^D] 4880rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net 4881.Ed 4882.Pp 4883or from a command run at completion time: 4884.Bd -literal -offset indent 4885> complete kill 'p/*/\`ps | awk \e{print\e \e$1\e}\`/' 4886> kill \-9 [^D] 488723113 23377 23380 23406 23429 23529 23530 PID 4888.Ed 4889.Pp 4890Note that the 4891.Ic complete 4892command does not itself quote its arguments, 4893so the braces, space and 4894.Ql $ 4895in 4896.Ql {print $1} 4897must be quoted explicitly. 4898.Pp 4899One command can have multiple completions: 4900.Bd -literal -offset indent 4901> complete dbx 'p/2/(core)/' 'p/*/c/' 4902.Ed 4903.Pp 4904completes the second argument to 4905.Ql dbx 4906with the word 4907.Ql core 4908and all other 4909arguments with commands. 4910Note that the positional completion is specified 4911before the next-word completion. 4912Because completions are evaluated from left to right, if 4913the next-word completion were specified first it would always match 4914and the positional completion would never be executed. 4915This is a 4916common mistake when defining a completion. 4917.Pp 4918The 4919.Ar select 4920pattern is useful when a command takes files with only 4921particular forms as arguments. 4922For example, 4923.Bd -literal -offset indent 4924> complete cc 'p/*/f:*.[cao]/' 4925.Ed 4926.Pp 4927completes 4928.Ql cc 4929arguments to files ending in only 4930.Ql .c , 4931.Ql .a , 4932or 4933.Ql .o . 4934.Ar select 4935can also exclude files, using negation of a glob-pattern as 4936described under 4937.Sx Filename substitution . 4938One might use 4939.Bd -literal -offset indent 4940> complete rm 'p/*/f:^*.{c,h,cc,C,tex,1,man,l,y}/' 4941.Ed 4942.Pp 4943to exclude precious source code from 4944.Ql rm 4945completion. 4946Of course, one 4947could still type excluded names manually or override the completion 4948mechanism using the 4949.Ic complete-word-raw 4950or 4951.Ic list-choices-raw 4952editor commands (q.v.). 4953.Pp 4954The 4955.Ql C , 4956.Ql D , 4957.Ql F , 4958and 4959.Ql T 4960.Ar list Ns s 4961are like 4962.Ql c , 4963.Ql d , 4964.Ql f , 4965and 4966.Ql t 4967respectively, but they use the 4968.Ar select 4969argument in a different way: to 4970restrict completion to files beginning with a particular path prefix. 4971For 4972example, the Elm mail program uses 4973.Ql = 4974as an abbreviation for one's mail 4975directory. 4976One might use 4977.Bd -literal -offset indent 4978> complete elm c@=@F:$HOME/Mail/@ 4979.Ed 4980.Pp 4981to complete 4982.Ql elm \-f = 4983as if it were 4984.Ql elm \-f ~/Mail/ . 4985Note that we used the separator 4986.Ql @ 4987instead of 4988.Ql / 4989to avoid confusion with the 4990.Ar select 4991argument, and we used 4992.Ql $HOME 4993instead of 4994.Ql ~ 4995because home directory substitution works at only the 4996beginning of a word. 4997.Pp 4998.Ar suffix 4999is used to add a nonstandard suffix 5000(not space or 5001.Ql / 5002for directories) to completed words. 5003.Bd -literal -offset indent 5004> complete finger 'c/*@/$hostnames/' 'p/1/u/@' 5005.Ed 5006.Pp 5007completes arguments to 5008.Ql finger 5009from the list of users, appends an 5010.Ql @ , 5011and then completes after the 5012.Ql @ 5013from the 5014.Ql hostnames 5015variable. 5016Note 5017again the order in which the completions are specified. 5018.Pp 5019Finally, here's a complex example for inspiration: 5020.Bd -literal -offset indent 5021> complete find \e 5022\&'n/\-name/f/' 'n/\-newer/f/' 'n/\-{,n}cpio/f/' \e 5023\&\'n/\-exec/c/' 'n/\-ok/c/' 'n/\-user/u/' \e 5024\&'n/\-group/g/' 'n/\-fstype/(nfs 4.2)/' \e 5025\&'n/\-type/(b c d f l p s)/' \e 5026\'c/\-/(name newer cpio ncpio exec ok user \e 5027group fstype type atime ctime depth inum \e 5028ls mtime nogroup nouser perm print prune \e 5029size xdev)/' \e 5030\&'p/*/d/' 5031.Ed 5032.Pp 5033This completes words following 5034.Ql \-name , 5035.Ql \-newer , 5036.Ql \-cpio , 5037or 5038.Ql ncpio 5039(note the pattern which matches both) to files, 5040words following 5041.Ql \-exec 5042or 5043.Ql \-ok 5044to commands, words following 5045.Ql user 5046and 5047.Ql group 5048to users and groups respectively 5049and words following 5050.Ql \-fstype 5051or 5052.Ql \-type 5053to members of the 5054given lists. 5055It also completes the switches themselves from the given list 5056(note the use of 5057.Ql c Ns 5058\-type completion) 5059and completes anything not otherwise completed to a directory. 5060Whew. 5061.Pp 5062Remember that programmed completions are ignored if the word being completed 5063is a tilde substitution (beginning with 5064.Ql ~ ) 5065or a variable (beginning with 5066.Ql $ ) . 5067See also the 5068.Ic uncomplete 5069builtin command. 5070. 5071.It Ic continue 5072Continues execution of the nearest enclosing 5073.Ic while 5074or 5075.Ic foreach . 5076The rest of the commands on the current line are executed. 5077. 5078.It Ic default: 5079Labels the default case in a 5080.Ic switch 5081statement. 5082It should come after all 5083.Ic case 5084labels. 5085. 5086.El 5087.Pp 5088.Bl -tag -width 8n -compact 5089. 5090.It Ic dirs Xo 5091.Op Fl l 5092.Op Fl n Ns | Ns Fl v 5093.Xc 5094.It Ic dirs Xo 5095.Fl S Ns | Ns Fl L 5096.Op Ar filename 5097(+) 5098.Xc 5099.It Ic dirs Xo 5100.Fl c 5101(+) 5102.Xc 5103The first form prints the directory stack. 5104The top of the stack is at the 5105left and the first directory in the stack is the current directory. 5106With 5107.Fl l , 5108.Ql ~ 5109or 5110.Ql ~ Ns Ar name 5111in the output is expanded explicitly 5112to 5113.Ic home 5114or the pathname of the home directory for user 5115.Ar name . 5116(+) 5117With 5118.Fl n , 5119entries are wrapped before they reach the edge of the screen. 5120(+) 5121With 5122.Fl v , 5123entries are printed one per line, preceded by their stack positions. 5124(+) 5125If more than one of 5126.Fl n 5127or 5128.Fl v 5129is given, 5130.Fl v 5131takes precedence. 5132.Fl p 5133is accepted but does nothing. 5134.Pp 5135With 5136.Fl S , 5137the second form saves the directory stack to 5138.Ar filename 5139as a series of 5140.Ic cd 5141and 5142.Ic pushd 5143commands. 5144With 5145.Fl L , 5146the shell sources 5147.Ar filename , 5148which is presumably 5149a directory stack file saved by the 5150.Fl S 5151option or the 5152.Ic savedirs 5153mechanism. 5154In either case, 5155.Ic dirsfile 5156is used if 5157.Ar filename 5158is not given and 5159.Pa ~/.cshdirs 5160is used if 5161.Ic dirsfile 5162is unset. 5163.Pp 5164Note that login shells do the equivalent of 5165.Ql dirs \-L 5166on startup 5167and, if 5168.Ic savedirs 5169is set, 5170.Ql dirs \-S 5171before exiting. 5172Because only 5173.Pa ~/.tcshrc 5174is normally sourced before 5175.Pa ~/.cshdirs , 5176.Ic dirsfile 5177should be set in 5178.Pa ~/.tcshrc 5179rather than 5180.Pa ~/.login . 5181.Pp 5182The third form clears the directory stack. 5183. 5184.El 5185.Bl -tag -width 8n 5186. 5187.It Ic echo Oo Fl n Oc Ar word No \&... 5188Writes each 5189.Ar word 5190to the shell's standard 5191output, separated by spaces and terminated with a newline. 5192The 5193.Ic echo_style 5194shell variable may be set to emulate (or not) the flags and escape 5195sequences of the BSD and/or System V versions of 5196.Xr echo 1 ; 5197see 5198.Sx Escape sequences 5199and 5200.Xr echo 1 . 5201. 5202.It Ic echotc Oo Fl sv Oc Ar arg No \&... No (+) 5203Exercises the terminal capabilities (see 5204.Xr termcap 5 ) 5205in 5206.Ar arg . 5207For example, 5208.Ql echotc home 5209sends the cursor to the home position, 5210.Ql echotc cm 3 10 5211sends it to column 3 and row 10, and 5212.Ql echotc ts 0; echo \&"This is a test.\&"; echotc fs 5213prints 5214.Sq This is a test. 5215in the status line. 5216.Pp 5217If 5218.Ar arg 5219is 5220.Ql baud , 5221.Ql cols , 5222.Ql lines , 5223.Ql meta , 5224or 5225.Ql tabs , 5226prints the 5227value of that capability 5228.Dq ( yes 5229or 5230.Dq no 5231indicating that the terminal does 5232or does not have that capability). 5233One might use this to make the output 5234from a shell script less verbose on slow terminals, or limit command 5235output to the number of lines on the screen: 5236.Bd -literal -offset indent 5237> set history=\`echotc lines\` 5238> @ history\-\- 5239.Ed 5240.Pp 5241Termcap strings may contain wildcards which will not echo correctly. 5242One should use double quotes when setting a shell variable to a terminal 5243capability string, as in the following example that places the date in 5244the status line: 5245.Bd -literal -offset indent 5246> set tosl="\`echotc ts 0\`" 5247> set frsl="\`echotc fs\`" 5248> echo \-n "$tosl";date; echo \-n "$frsl" 5249.Ed 5250.Pp 5251With 5252.Fl s , 5253nonexistent capabilities return the empty string rather 5254than causing an error. 5255With 5256.Fl v , 5257messages are verbose. 5258.Pp 5259. 5260.El 5261.Pp 5262.Bl -tag -width 8n -compact 5263. 5264.It Ic else 5265.It Ic end 5266.It Ic endif 5267.It Ic endsw 5268See the description of the 5269.Ic foreach , 5270.Ic if , 5271.Ic switch , 5272and 5273.Ic while 5274statements below. 5275. 5276.El 5277.Bl -tag -width 8n 5278. 5279.It Ic eval Ar arg No \&... 5280Treats the arguments as input to the 5281shell and executes the resulting command(s) in the context 5282of the current shell. 5283This is usually used to execute commands 5284generated as the result of command or variable substitution, 5285because parsing occurs before these substitutions. 5286See 5287.Xr tset 1 5288for a sample use of 5289.Ic eval . 5290. 5291.It Ic exec Ar command No \&... 5292Executes the specified 5293.Ar command 5294in place of the current shell. 5295. 5296.It Ic exit Op Ar expr 5297The shell exits either with the value of the specified 5298.Ar expr 5299(an expression, as described under 5300.Sx Expressions ) 5301or, without 5302.Ar expr , 5303with the value 0. 5304. 5305.It Ic fg Op Cm % Ns Ar job No \&... 5306Brings the specified jobs (or, without arguments, the current job) 5307into the foreground, continuing each if it is stopped. 5308.Ar job 5309may be a number, a string, 5310.Ql \& , 5311.Ql % , 5312.Ql + , 5313or 5314.Ql \- 5315as described under 5316.Sx Jobs . 5317See also the 5318.Ic run-fg-editor 5319editor command. 5320. 5321.It Ic filetest \- Ns Ar op file No \&... No (+) 5322Applies 5323.Ar op 5324(which is a file inquiry operator as described under 5325.Sx File inquiry operators ) 5326to each 5327.Ar file 5328and returns the results as a 5329space-separated list. 5330. 5331.El 5332.Pp 5333.Bl -tag -width 8n -compact 5334. 5335.It Ic foreach Ar name Cm \&( Ns Ar wordlist Ns Cm \&) 5336.It Ic \&... 5337.It Ic end 5338Successively sets the variable 5339.Ar name 5340to each member of 5341.Ar wordlist 5342and executes the sequence of commands between this command 5343and the matching 5344.Ic end . 5345(Both 5346.Ic foreach 5347and 5348.Ic end 5349must appear alone on separate lines.) The builtin command 5350.Ic continue 5351may be used to continue the loop prematurely and 5352the builtin command 5353.Ic break 5354to terminate it prematurely. 5355When this command is read from the terminal, the loop is read once 5356prompting with 5357.Sq Li foreach?\ \& 5358(or 5359.Ic prompt2 ) 5360before any statements in 5361the loop are executed. 5362If you make a mistake typing in a 5363loop at the terminal you can rub it out. 5364. 5365.El 5366.Bl -tag -width 8n 5367. 5368.It Ic getspath No (+) 5369Prints the system execution path. 5370(TCF only) 5371. 5372.It Ic getxvers No (+) 5373Prints the experimental version prefix. 5374(TCF only) 5375. 5376.It Ic glob Ar word No \&... 5377Like 5378.Ic echo , 5379but the 5380.Fl n 5381parameter is not recognized and words are 5382delimited by null characters in the output. 5383Useful for 5384programs which wish to use the shell to filename expand a list of words. 5385. 5386.It Ic goto Ar word 5387.Ar word 5388is filename and command-substituted to 5389yield a string of the form 5390.Sq Ar label . 5391The shell rewinds its 5392input as much as possible, searches for a line of the 5393form 5394.Sq Ar label Ns No \&: , 5395possibly preceded by blanks or tabs, and 5396continues execution after that line. 5397. 5398.It Ic hashstat 5399Prints a statistics line indicating how effective the 5400internal hash table has been at locating commands (and avoiding 5401.Ic exec Ns 5402\&'s). 5403An 5404.Ic exec 5405is attempted for each component of the 5406.Ic path 5407where the hash function indicates a possible hit, and 5408in each component which does not begin with a 5409.Ql / . 5410.Pp 5411On machines without 5412.Xr vfork 2 , 5413prints only the number and size of 5414hash buckets. 5415. 5416.El 5417.Pp 5418.Bl -tag -width 8n -compact 5419. 5420.It Ic history Xo 5421.Op Fl hTr 5422.Op Ar n 5423.Xc 5424.It Ic history Xo 5425.Fl S Ns | Ns Fl L Ns | Ns Fl M 5426.Op Ar filename 5427(+) 5428.Xc 5429.It Ic history Xo 5430.Fl c 5431(+) 5432.Xc 5433The first form prints the history event list. 5434If 5435.Ar n 5436is given only the 5437.Ar n 5438most recent events are printed or saved. 5439With 5440.Fl h , 5441the history list is printed without leading numbers. 5442If 5443.Fl T 5444is specified, timestamps are printed also in comment form. 5445(This can be used to 5446produce files suitable for loading with 5447.Ql history \-L 5448or 5449.Ql source \-h . ) 5450With 5451.Fl r , 5452the order of printing is most recent 5453first rather than oldest first. 5454.Pp 5455With 5456.Fl S , 5457the second form saves the history list to 5458.Ar filename . 5459If the first word of the 5460.Ic savehist 5461shell variable is set to a 5462number, at most that many lines are saved. 5463If the second word of 5464.Ic savehist 5465is set to 5466.Ql merge , 5467the history list is merged with the 5468existing history file instead of replacing it (if there is one) and 5469sorted by time stamp. 5470(+) Merging is intended for an environment like 5471the X Window System 5472with several shells in simultaneous use. 5473If the second word of 5474.Ic savehist 5475is 5476.Ql merge 5477and the third word is set to 5478.Ql lock , 5479the history file update 5480will be serialized with other shell sessions that would possibly like 5481to merge history at exactly the same time. 5482.Pp 5483With 5484.Fl L , 5485the shell appends 5486.Ar filename , 5487which is presumably a 5488history list saved by the 5489.Fl S 5490option or the 5491.Ic savehist 5492mechanism, 5493to the history list. 5494.Fl M 5495is like 5496.Fl L , 5497but the contents of 5498.Ar filename 5499are merged 5500into the history list and sorted by timestamp. 5501In either case, 5502.Ic histfile 5503is used if 5504.Ar filename 5505is not given and 5506.Pa ~/.history 5507is used if 5508.Ic histfile 5509is unset. 5510.Ql history \-L 5511is exactly like 5512.Ql source \-h 5513except that it does not require a 5514filename. 5515.Pp 5516Note that login shells do the equivalent of 5517.Ql history \-L 5518on startup 5519and, if 5520.Ic savehist 5521is set, 5522.Ql history \-S 5523before exiting. 5524Because only 5525.Pa ~/.tcshrc 5526is normally sourced before 5527.Pa ~/.history , 5528.Ic histfile 5529should be set in 5530.Pa ~/.tcshrc 5531rather than 5532.Pa ~/.login . 5533.Pp 5534If 5535.Ic histlit 5536is set, the first and second forms print and save the literal 5537(unexpanded) form of the history list. 5538.Pp 5539The third form clears the history list. 5540. 5541.El 5542.Bl -tag -width 8n 5543. 5544.It Ic hup Oo Ar command Oc No (+) 5545With 5546.Ar command , 5547runs 5548.Ar command 5549such that it will exit on a hangup 5550signal and arranges for the shell to send it a hangup signal when the shell 5551exits. 5552Note that commands may set their own response to hangups, overriding 5553.Ic hup . 5554Without an argument, causes the non-interactive shell only to 5555exit on a hangup for the remainder of the script. 5556See also 5557.Sx Signal handling 5558and the 5559.Ic nohup 5560builtin command. 5561. 5562.It Ic if Cm \&( Ns Ar expr Ns Cm \&) Ar command 5563If 5564.Ar expr 5565(an expression, as described under 5566.Sx Expressions ) 5567evaluates true, then 5568.Ar command 5569is executed. 5570Variable substitution on 5571.Ar command 5572happens early, at the same time it 5573does for the rest of the 5574.Ic if 5575command. 5576.Ar command 5577must be a simple command, not an alias, a pipeline, a command list 5578or a parenthesized command list, but it may have arguments. 5579Input/output redirection occurs even if 5580.Ar expr 5581is 5582false and 5583.Ar command 5584is thus 5585.Em not 5586executed; this is a bug. 5587. 5588.El 5589.Pp 5590.Bl -tag -width 8n -compact 5591. 5592.It Ic if Cm \&( Ns Ar expr Ns Cm \&) then 5593.It Ic \&... 5594.It Ic else if Cm \&( Ns Ar expr2 Ns Cm \&) then 5595.It Ic \&... 5596.It Ic else 5597.It Ic \&... 5598.It Ic endif 5599If the specified 5600.Ar expr 5601is true then the commands to the 5602first 5603.Ic else 5604are executed; otherwise if 5605.Ar expr2 5606is true then 5607the commands to the second 5608.Ic else 5609are executed, etc. 5610Any 5611number of 5612.Ic else if 5613pairs are possible; only one 5614.Ic endif 5615is 5616needed. 5617The 5618.Ic else 5619part is likewise optional. 5620(The words 5621.Ic else 5622and 5623.Ic endif 5624must appear at the beginning of input lines; 5625the 5626.Ic if 5627must appear alone on its input line or after an 5628.Ic else . ) 5629. 5630.El 5631.Pp 5632.Bl -tag -width 8n -compact 5633. 5634.It Ic inlib Ar shared-library No \&... No (+) 5635Adds each 5636.Ar shared-library 5637to the current environment. 5638There is no way 5639to remove a shared library. 5640(Domain/OS only) 5641. 5642.El 5643.Pp 5644.Bl -tag -width 8n -compact 5645. 5646.It Ic jobs Op Fl l 5647.It Ic jobs Fl Z Oo Ar title Oc No (+) 5648Lists the active jobs. 5649With 5650.Fl l , 5651lists process IDs in addition to the normal information. 5652On TCF systems, prints the site on which each job is executing. 5653.Pp 5654The 5655.Fl Z 5656option sets the process title to 5657.Ar title 5658using 5659.Xr setproctitle 3 5660where available. 5661If no 5662.Ar title 5663is provided, the process title will be cleared. 5664. 5665.\" adjacant multi-tag items; add a blank 5666.Pp 5667. 5668.It Ic kill Fl l 5669.It Ic kill Xo 5670.Op Fl s Ar signal 5671.Cm % Ns Ar job Ns | Ns Ar pid No \&... 5672.Xc 5673The first form lists the signal names. 5674.Pp 5675The second form sends the specified 5676.Ar signal 5677(or, if none 5678is given, the TERM (terminate) signal) to the specified jobs or processes. 5679.Ar job 5680may be a number, a string, 5681.Ql \& , 5682.Ql % , 5683.Ql + , 5684or 5685.Ql \- 5686as described under 5687.Sx Jobs . 5688Signals are either given by number or by name (as given in 5689.Pa /usr/include/signal.h , 5690stripped of the prefix 5691.Sq SIG ) . 5692There is no default 5693.Ar job ; 5694entering just 5695.Ql kill 5696does not send a signal 5697to the current job. 5698If the signal being sent is TERM (terminate) 5699or HUP (hangup), then the job or process is sent a 5700CONT (continue) signal as well. 5701. 5702.El 5703.Bl -tag -width 8n 5704. 5705.It Ic limit Oo Fl h Oc Op Ar resource Op Ar maximum-use 5706Limits the consumption by the current process and each 5707process it creates to not individually exceed 5708.Ar maximum-use 5709on 5710the specified 5711.Ar resource . 5712If no 5713.Ar maximum-use 5714is given, then 5715the current limit is printed; if no 5716.Ar resource 5717is given, then 5718all limitations are given. 5719If the 5720.Fl h 5721flag is given, the 5722hard limits are used instead of the current limits. 5723The 5724hard limits impose a ceiling on the values of the current 5725limits. 5726Only the super-user may raise the hard limits, but 5727a user may lower or raise the current limits within the legal range. 5728.Pp 5729Controllable 5730.Ar resource 5731types currently include (if supported by the OS): 5732.Bl -tag -width 12n -offset indent 5733. 5734.It Ic concurrency 5735Maximum number of threads for this process. 5736. 5737.It Ic coredumpsize 5738Size of the largest core dump that will be created. 5739. 5740.It Ic cputime 5741Maximum number of cpu-seconds to be used by each process. 5742. 5743.It Ic datasize 5744Maximum growth of the data+stack region via 5745.Xr sbrk 2 5746beyond the end of the program text. 5747. 5748.It Ic descriptors No or Ic openfiles 5749Maximum number of open files for this process. 5750. 5751.It Ic filesize 5752Largest single file which can be created. 5753. 5754.It Ic heapsize 5755Maximum amount of memory a process 5756may allocate per 5757.Xr brk 2 5758system call. 5759. 5760.It Ic kqueues 5761Maximum number of kqueues allocated for this process. 5762. 5763.It Ic maxlocks 5764Maximum number of locks for this user. 5765. 5766.It Ic maxmessage 5767Maximum number of bytes in POSIX mqueues for this user. 5768. 5769.It Ic maxnice 5770Maximum nice priority the user is allowed to raise mapped from [19...-20] 5771to [0...39] for this user. 5772. 5773.It Ic maxproc 5774Maximum number of simultaneous processes for this user id. 5775. 5776.It Ic maxrtprio 5777Maximum realtime priority for this user. 5778. 5779.It Ic maxrttime 5780Timeout for RT tasks in microseconds for this user. 5781. 5782.It Ic maxsignal 5783Maximum number of pending signals for this user. 5784. 5785.It Ic maxthread 5786Maximum number of simultaneous threads (lightweight processes) for this 5787user id. 5788. 5789.It Ic memorylocked 5790Maximum size which a process may lock into memory using 5791.Xr mlock 2 . 5792. 5793.It Ic memoryuse 5794Maximum amount of physical memory a process 5795may have allocated to it at a given time. 5796. 5797.It Ic posixlocks 5798Maximum number of POSIX advisory locks for this user. 5799. 5800.It Ic pseudoterminals 5801Maximum number of pseudo-terminals for this user. 5802. 5803.It Ic sbsize 5804Maximum size of socket buffer usage for this user. 5805. 5806.It Ic stacksize 5807Maximum size of the automatically-extended stack region. 5808. 5809.It Ic swapsize 5810Maximum amount of swap space reserved or used for this user. 5811. 5812.It Ic threads 5813Maximum number of threads for this process. 5814. 5815.It Ic vmemoryuse 5816Maximum amount of virtual memory a process 5817may have allocated to it at a given time (address space). 5818. 5819.El 5820.Pp 5821.Ar maximum-use 5822may be given as a (floating point or 5823integer) number followed by a scale factor. 5824For all limits 5825other than 5826.Ic cputime 5827the default scale is 5828.Ql k 5829or 5830.Ql kilobytes 5831(1024 bytes); a scale factor of 5832.Ql m 5833or 5834.Ql megabytes 5835or 5836.Ql g 5837or 5838.Ql gigabytes 5839may also be used. 5840For 5841.Ic cputime 5842the default scaling is 5843.Ql seconds , 5844while 5845.Ql m 5846for minutes or 5847.Ql h 5848for hours, or a time of the 5849form 5850.Sq Ar mm Ns Li : Ns Ar ss 5851giving minutes and seconds may be used. 5852.Pp 5853If 5854.Ar maximum-use 5855is 5856.Ql unlimited , 5857then the limitation on the specified 5858.Ar resource 5859is removed (this is equivalent to the 5860.Ic unlimit 5861builtin command). 5862.Pp 5863For both 5864.Ar resource 5865names and scale factors, unambiguous 5866prefixes of the names suffice. 5867. 5868.It Ic log No (+) 5869Prints the 5870.Ic watch 5871shell variable and reports on each user indicated 5872in 5873.Ic watch 5874who is logged in, regardless of when they last logged in. 5875See also 5876.Ic watchlog . 5877. 5878.It Ic login 5879Terminates a login shell, replacing it with an instance of 5880.Pa /bin/login . 5881This is one way to log off, included for 5882compatibility with 5883.Xr sh 1 . 5884. 5885.It Ic logout 5886Terminates a login shell. 5887Especially useful if 5888.Ic ignoreeof 5889is set. 5890. 5891.It Ic ls\-F Xo 5892.Op Fl Ar switch No \&... 5893.Op Ar file No \&... 5894(+) 5895.Xc 5896Lists files like 5897.Ql ls \-F , 5898but much faster. 5899It identifies each type of 5900special file in the listing with a special character: 5901.Pp 5902.Bl -tag -width 5n -offset indent -compact 5903.It Li / 5904Directory. 5905.It Li * 5906Executable. 5907.It Li # 5908Block device. 5909.It Li % 5910Character device. 5911.It Li | 5912Named pipe (systems with named pipes only). 5913.It Li = 5914Socket (systems with sockets only). 5915.It Li @ 5916Symbolic link (systems with symbolic links only). 5917.It Li + 5918Hidden directory (AIX only) or context dependent (HP/UX only). 5919.It Li : 5920Network special (HP/UX only). 5921.El 5922.Pp 5923If the 5924.Ic listlinks 5925shell variable is set, symbolic links are identified 5926in more detail (on only systems that have them, of course): 5927.Pp 5928.Bl -tag -width 5n -offset indent -compact 5929.It Li @ 5930Symbolic link to a non-directory. 5931.It Li > 5932Symbolic link to a directory. 5933.It Li & 5934Symbolic link to nowhere. 5935.El 5936.Pp 5937.Ic listlinks 5938also slows down 5939.Ic ls\-F 5940and causes partitions holding 5941files pointed to by symbolic links to be mounted. 5942.Pp 5943If the 5944.Ic listflags 5945shell variable is set to 5946.Ql x , 5947.Ql a , 5948or 5949.Ql A , 5950or any 5951combination thereof (e.g., 5952.Ql xA ) , 5953they are used as flags to 5954.Ic ls\-F , 5955making it act like 5956.Ql ls \-xF , 5957.Ql ls \-Fa , 5958.Ql ls \-FA , 5959or a combination 5960(e.g., 5961.Ql ls \-FxA ) . 5962On machines where 5963.Ql ls \-C 5964is not the default, 5965.Ic ls\-F 5966acts like 5967.Ql ls \-CF , 5968unless 5969.Ic listflags 5970contains an 5971.Ql x , 5972in which case it acts like 5973.Ql ls \-xF . 5974.Ic ls\-F 5975passes its arguments to 5976.Xr ls 1 5977if it is given any switches, 5978so 5979.Ql alias ls ls\-F 5980generally does the right thing. 5981.Pp 5982The 5983.Ic ls\-F 5984builtin can list files using different colors depending on the 5985filetype or extension. 5986See the 5987.Ic color 5988shell variable and the 5989.Ev LS_COLORS 5990environment variable. 5991.El 5992.Pp 5993.Bl -tag -width 8n -compact 5994. 5995.It Ic migrate Xo 5996.Op Fl Ar site 5997.Ar pid Ns | Ns Cm % Ns Ar jobid No \&... (+) 5998.Xc 5999.It Ic migrate Fl Ar site No (+) 6000The first form migrates the process or job to the site specified or the 6001default site determined by the system path. 6002(TCF only) 6003.Pp 6004The second form is equivalent to 6005.Ql migrate \- Ns Ar site Li $$ : 6006it migrates the 6007current process to the specified site. 6008Migrating the shell 6009itself can cause unexpected behavior, because the shell 6010does not like to lose its tty. 6011(TCF only) 6012.El 6013.Bl -tag -width 8n 6014. 6015.It Ic newgrp Oo Cm \- Oc Oo Ar group Oc No (+) 6016Equivalent to 6017.Ql exec newgrp ; 6018see 6019.Xr newgrp 1 . 6020Available only if the shell was so compiled; 6021see the 6022.Ic version 6023shell variable. 6024. 6025.It Ic nice Oo Cm + Ns Ar number Oc Op Ar command 6026Sets the scheduling priority for the shell to 6027.Ar number , 6028or, without 6029.Ar number , 6030to 4. 6031With 6032.Ar command , 6033runs 6034.Ar command 6035at the appropriate 6036priority. 6037The greater the 6038.Ar number , 6039the less cpu 6040the process gets. 6041The super-user may specify negative 6042priority by using 6043.Ql nice \- Ns Ar number Li \&... . 6044Command is always 6045executed in a sub-shell, and the restrictions placed on 6046commands in simple 6047.Ic if 6048statements apply. 6049. 6050.It Ic nohup Op Ar command 6051With 6052.Ar command , 6053runs 6054.Ar command 6055such that it will ignore hangup signals. 6056Note that commands may set their own response to hangups, overriding 6057.Ic nohup . 6058Without an argument, causes the non-interactive shell only to 6059ignore hangups for the remainder of the script. 6060See also 6061.Sx Signal handling 6062and the 6063.Ic hup 6064builtin command. 6065. 6066.It Ic notify Op Cm % Ns Ar job No \&... 6067Causes the shell to notify the user asynchronously when the status of any 6068of the specified jobs (or, without 6069.Cm % Ns Ar job , 6070the current job) changes, 6071instead of waiting until the next prompt as is usual. 6072.Ar job 6073may be a number, a string, 6074.Ql \& , 6075.Ql % , 6076.Ql + , 6077or 6078.Ql \- 6079as described under 6080.Sx Jobs . 6081See also the 6082.Ic notify 6083shell variable. 6084. 6085.It Ic onintr Op Cm \- Ns | Ns Ar label 6086Controls the action of the shell on interrupts. 6087Without arguments, 6088restores the default action of the shell on interrupts, 6089which is to terminate shell scripts or to return to the 6090terminal command input level. 6091With 6092.Ql \- , 6093causes all interrupts to be ignored. 6094With 6095.Ar label , 6096causes the shell to execute a 6097.Ql goto Ar label 6098when an interrupt is received or a child process terminates because it was 6099interrupted. 6100.Pp 6101.Ic onintr 6102is ignored if the shell is running detached and in system 6103startup files (see 6104.Sx FILES ) , 6105where interrupts are disabled anyway. 6106. 6107.It Ic popd Xo 6108.Op Fl p 6109.Op Fl l 6110.Op Fl n Ns | Ns Fl v 6111.Op Cm + Ns Ar n 6112.Xc 6113Without arguments, pops the directory stack and returns to the new top directory. 6114With a number 6115.Ql + Ns Ar n , 6116discards the 6117.Ar n Ns 6118th entry in the stack. 6119.Pp 6120Finally, all forms of 6121.Ic popd 6122print the final directory stack, 6123just like 6124.Ic dirs . 6125The 6126.Ic pushdsilent 6127shell variable can be set to 6128prevent this and the 6129.Fl p 6130flag can be given to override 6131.Ic pushdsilent . 6132The 6133.Fl l , 6134.Fl n , 6135and 6136.Fl v 6137flags have the same effect on 6138.Ic popd 6139as on 6140.Ic dirs. 6141(+) 6142. 6143.It Ic printenv Oo Ar name Oc No (+) 6144Prints the names and values of all environment variables or, 6145with 6146.Ar name , 6147the value of the environment variable 6148.Ar name . 6149. 6150.It Ic pushd Xo 6151.Op Fl p 6152.Op Fl l 6153.Op Fl n Ns | Ns Fl v 6154.Op Ar name Ns | Ns Cm + Ns Ar n 6155.Xc 6156Without arguments, exchanges the top two elements of the directory stack. 6157If 6158.Ic pushdtohome 6159is set, 6160.Ic pushd 6161without arguments does 6162.Ql pushd ~ , 6163like 6164.Ic cd . 6165(+) 6166With 6167.Ar name , 6168pushes the current working directory onto the directory 6169stack and changes to 6170.Ar name . 6171If 6172.Ar name 6173is 6174.Ql \- 6175it is interpreted as the previous working directory 6176(see 6177.Sx Filename substitution ) . 6178(+) 6179If 6180.Ic dunique 6181is set, 6182.Ic pushd 6183removes any instances of 6184.Ar name 6185from the stack before pushing it onto the stack. 6186(+) 6187With a number 6188.Ql + Ns Ar n , 6189rotates the 6190.Ar n Ns 6191th element of the 6192directory stack around to be the top element and changes to it. 6193If 6194.Ic dextract 6195is set, however, 6196.Ql pushd + Ns Ar n 6197extracts the 6198.Ar n Ns 6199th 6200directory, pushes it onto the top of the stack and changes to it. 6201(+) 6202.Pp 6203Finally, all forms of 6204.Ic pushd 6205print the final directory stack, 6206just like 6207.Ic dirs . 6208The 6209.Ic pushdsilent 6210shell variable can be set to 6211prevent this and the 6212.Fl p 6213flag can be given to override 6214.Ic pushdsilent . 6215The 6216.Fl l , 6217.Fl n , 6218and 6219.Fl v 6220flags have the same effect on 6221.Ic pushd 6222as on 6223.Ic dirs . 6224(+) 6225. 6226.It Ic rehash 6227Causes the internal hash table of the contents of the 6228directories in the 6229.Ic path 6230variable to be recomputed. 6231This is 6232needed if the 6233.Ic autorehash 6234shell variable is not set and new 6235commands are added to directories in 6236.Ic path 6237while you are logged 6238in. 6239With 6240.Ic autorehash , 6241a new command will be found 6242automatically, except in the special case where another command of 6243the same name which is located in a different directory already 6244exists in the hash table. 6245Also flushes the cache of home directories 6246built by tilde expansion. 6247. 6248.It Ic repeat Ar count Ar command 6249The specified 6250.Ar command , 6251which is subject to the same restrictions as the 6252.Ar command 6253in the one line 6254.Ic if 6255statement above, is executed 6256.Ar count 6257times. 6258I/O redirections occur exactly once, even if 6259.Ar count 6260is 0. 6261. 6262.It Ic rootnode Cm // Ns Ar nodename No (+) 6263Changes the rootnode to 6264.Pa // Ns Ar nodename , 6265so that 6266.Ql / 6267will be interpreted 6268as 6269.Ql // Ns Ar nodename . 6270(Domain/OS only) 6271. 6272.El 6273.Pp 6274.Bl -tag -width 8n -compact 6275. 6276.It Ic sched No (+) 6277.It Ic sched Xo 6278.Op Cm + Ns 6279.Ar hh Ns Cm : Ns Ar mm 6280.Ar command 6281(+) 6282.Xc 6283.It Ic sched Cm \- Ns Ar n No (+) 6284The first form prints the scheduled-event list. 6285The 6286.Ic sched 6287shell variable may be set to define the format in which 6288the scheduled-event list is printed. 6289.Pp 6290The second form adds 6291.Ar command 6292to the scheduled-event list. 6293For example, 6294.Bd -literal -offset indent 6295> sched 11:00 echo It\e's eleven o\e'clock. 6296.Ed 6297.Pp 6298causes the shell to echo 6299.Sq It's eleven o'clock. 6300at 11 AM. 6301The time may be in 12-hour AM/PM format 6302.Bd -literal -offset indent 6303.\" TODO 6304> sched 5pm set prompt='[%h] It\e's after 5; go home: >' 6305.Ed 6306.Pp 6307or may be relative to the current time: 6308.Bd -literal -offset indent 6309> sched +2:15 /usr/lib/uucp/uucico \-r1 \-sother 6310.Ed 6311.Pp 6312A relative time specification may not use AM/PM format. 6313.Pp 6314The third form removes item 6315.Ar n 6316from the event list: 6317.Bd -literal -offset indent 6318> sched 63191 Wed Apr 4 15:42 /usr/lib/uucp/uucico \-r1 \-sother 63202 Wed Apr 4 17:00 set prompt=[%h] It's after 5; go home: > 6321> sched \-2 6322> sched 63231 Wed Apr 4 15:42 /usr/lib/uucp/uucico \-r1 \-sother 6324.Ed 6325.Pp 6326A command in the scheduled-event list is executed just before the first 6327prompt is printed after the time when the command is scheduled. 6328It is possible to miss the exact time when the command is to be run, but 6329an overdue command will execute at the next prompt. 6330A command which comes due while the shell 6331is waiting for user input is executed immediately. 6332However, normal operation of an already-running command will not 6333be interrupted so that a scheduled-event list element may be run. 6334.Pp 6335This mechanism is similar to, but not the same as, the 6336.Xr at 1 6337command on some Unix systems. 6338Its major disadvantage is that it may not run a command at exactly the 6339specified time. 6340Its major advantage is that because 6341.Ic sched 6342runs directly from 6343the shell, it has access to shell variables and other structures. 6344This provides a mechanism for changing one's working environment 6345based on the time of day. 6346. 6347.\" adjacant multi-tag items; add a blank 6348.Pp 6349. 6350.It Ic set 6351.It Ic set Ar name No \&... 6352.It Ic set Ar name Ns Cm = Ns Ar word No \&... 6353.It Ic set Xo 6354.Op Fl r 6355.Op Fl f Ns | Ns Fl l 6356.Ar name Ns Cm =\&( Ns Ar wordlist Ns Cm \&) No \&... 6357(+) 6358.Xc 6359.It Ic set Ar name Ns Cm [ Ns Ar index Ns Cm ]= Ns Ar word No \&... 6360.It Ic set Fl r No (+) 6361.It Ic set Fl r Ar name No \&... No (+) 6362.It Ic set Fl r Ar name Ns Cm = Ns Ar word No \&... No (+) 6363The first form of the command prints the value of all shell variables. 6364Variables which contain more than a single word print as a 6365parenthesized word list. 6366.Pp 6367The second form sets 6368.Ar name 6369to the null string. 6370.Pp 6371The third form sets 6372.Ar name 6373to the single 6374.Ar word . 6375.Pp 6376The fourth form sets 6377.Ar name 6378to the list of words in 6379.Ar wordlist . 6380.Pp 6381In all cases the value is command and filename expanded. 6382If 6383.Fl r 6384is specified, the value is set read-only. 6385If 6386.Fl f 6387or 6388.Fl l 6389are specified, set only unique words keeping their order. 6390.Fl f 6391prefers the first occurrence of a word, and 6392.Fl l 6393the last. 6394.Pp 6395The fifth form sets the 6396.Ar index Ns 6397\&'th component of 6398.Ar name 6399to 6400.Ar word ; 6401this component must already exist. 6402.Pp 6403The sixth form lists only the names of all shell variables that are read-only. 6404.Pp 6405The seventh form makes 6406.Ar name 6407read-only, whether or not it has a value. 6408.Pp 6409The eighth form is the same as the third form, but 6410make 6411.Ar name 6412read-only at the same time. 6413.Pp 6414These arguments can be repeated to set and/or make read-only multiple variables 6415in a single set command. 6416Note, however, that variable expansion 6417happens for all arguments before any setting occurs. 6418Note also that 6419.Ql = 6420can 6421be adjacent to both 6422.Ar name 6423and 6424.Ar word 6425or separated from both by 6426whitespace, but cannot be adjacent to only one or the other. 6427See also the 6428.Ic unset 6429builtin command. 6430. 6431.El 6432.Bl -tag -width 8n 6433. 6434.It Ic setenv Op Ar name Op Ar value 6435Without arguments, prints the names and values of all environment variables. 6436Given 6437.Ar name , 6438sets the environment variable 6439.Ar name 6440to 6441.Ar value 6442or, without 6443.Ar value , 6444to the null string. 6445. 6446.It Ic setpath Ar path No (+) 6447Equivalent to 6448.Xr setpath 1 . 6449(Mach only) 6450. 6451.It Ic setspath Cm LOCAL Ns | Ns Ar site Ns | Ns Ar cpu No \&... No (+) 6452Sets the system execution path. 6453(TCF only) 6454. 6455.It Ic settc Ar cap value No (+) 6456Tells the shell to believe that the terminal capability 6457.Ar cap 6458(as defined in 6459.Xr termcap 5 ) 6460has the value 6461.Ar value . 6462No sanity checking is done. 6463Concept terminal users may have to 6464.Ql settc xn no 6465to get proper 6466wrapping at the rightmost column. 6467. 6468.It Ic setty Xo 6469.Op Fl d Ns | Ns Fl q Ns | Ns Fl x 6470.Op Fl a 6471.Op Oo Cm + Ns | Ns Cm \- Oc Ns Ar mode 6472(+) 6473.Xc 6474Controls which tty modes (see 6475.Sx Terminal management ) 6476the shell does not allow to change. 6477.Fl d , 6478.Fl q , 6479or 6480.Fl x 6481tells 6482.Ic setty 6483to act 6484on the 6485.Ql edit , 6486.Sq quote , 6487or 6488.Sq execute 6489set of tty modes respectively; without 6490.Fl d , 6491.Fl q , 6492or 6493.Fl x , 6494.Sq execute 6495is used. 6496.Pp 6497Without other arguments, 6498.Ic setty 6499lists the modes in the chosen set 6500which are fixed on 6501.Pq Sq Cm + Ns Ar mode 6502or off 6503.Pq Sq Cm - Ns Ar mode . 6504The available modes, and thus the display, vary from system to system. 6505With 6506.Fl a , 6507lists all tty modes in the chosen set 6508whether or not they are fixed. 6509With 6510.Cm + Ns Ar mode , 6511.Cm - Ns Ar mode , 6512or 6513.Ar mode , 6514fixes 6515.Ar mode 6516on or off 6517or removes control from 6518.Ar mode 6519in the chosen set. 6520For example, 6521.Ql setty +echok echoe 6522fixes 6523.Ql echok 6524mode on and allows commands 6525to turn 6526.Ql echoe 6527mode on or off, both when the shell is executing commands. 6528. 6529.It Ic setxvers Oo Ar string Oc No (+) 6530Set the experimental version prefix to 6531.Ar string , 6532or removes it 6533if 6534.Ar string 6535is omitted. 6536(TCF only) 6537. 6538.It Ic shift Op Ar variable 6539Without arguments, discards 6540.Ic argv Ns [1] 6541and shifts the members of 6542.Ic argv 6543to the left. 6544It is an error for 6545.Ic argv 6546not to be set or to have 6547less than one word as value. 6548With 6549.Ar variable , 6550performs the 6551same function on 6552.Ar variable . 6553. 6554.It Ic source Oo Fl h Oc Ar name Op Ar args No \&... 6555The shell reads and executes commands from 6556.Ar name . 6557The commands are not placed on the history list. 6558If any 6559.Ar args 6560are given, they are placed in 6561.Ic argv . 6562(+) 6563.Ic source 6564commands may be nested; 6565if they are nested too deeply the shell may run out of file descriptors. 6566An error in a 6567.Ic source 6568at any level terminates all nested 6569.Ic source 6570commands. 6571With 6572.Fl h , 6573commands are placed on the history list instead of being 6574executed, much like 6575.Ql history \-L . 6576. 6577.It Ic stop % Ns Ar job Ns | Ns Ar pid No \&... 6578Stops the specified jobs or processes which are executing in the background. 6579.Ar job 6580may be a number, a string, 6581.Ql \& , 6582.Ql % , 6583.Ql + , 6584or 6585.Ql \- 6586as described under 6587.Sx Jobs . 6588There is no default 6589.Ar job ; 6590entering just 6591.Ql stop 6592does not stop 6593the current job. 6594. 6595.It Ic suspend 6596Causes the shell to stop in its tracks, much as if it had 6597been sent a stop signal with 6598.Sq ^Z . 6599This is most often used to 6600stop shells started by 6601.Xr su 1 . 6602. 6603.El 6604.Pp 6605.Bl -tag -width 8n -compact 6606. 6607.It Ic switch Cm \&( Ns Ar string Ns Cm \&) 6608.It Ic case Ar str1 Ns : 6609.It Ic \ \ \ \ \&... 6610.It Ic \ \ \ \ breaksw 6611.It Ic \&... 6612.It Ic default: 6613.It Ic \ \ \ \ \&... 6614.It Ic \ \ \ \ breaksw 6615.It Ic endsw 6616Each case label is successively matched, against the 6617specified 6618.Ar string 6619which is first command and filename expanded. 6620The file metacharacters 6621.Ql * , 6622.Ql \&? , 6623and 6624.Ql [...] 6625may be used 6626in the case labels, which are variable expanded. 6627If none 6628of the labels match before a 6629.Ic default 6630label is found, then 6631the execution begins after the 6632.Ic default 6633label. 6634Each case 6635label and the 6636.Ic default 6637label must appear at the beginning of 6638a line. 6639The command 6640.Ic breaksw 6641causes execution to continue 6642after the 6643.Ic endsw . 6644Otherwise control may fall through case 6645labels and default labels as in C. 6646If no label matches and 6647there is no default, execution continues after the 6648.Ic endsw . 6649. 6650.El 6651.Bl -tag -width 8n 6652. 6653.It Ic telltc No (+) 6654Lists the values of all terminal capabilities (see 6655.Xr termcap 5 ) . 6656. 6657.It Ic termname Oo Ar termtype Oc No (+) 6658Tests if 6659.Ar termtype 6660(or the current value of 6661.Ev TERM 6662if no 6663.Ar termtype 6664is given) has an entry in the hosts 6665.Xr termcap 5 6666or 6667.Xr terminfo 5 6668database. Prints the terminal type to stdout and returns 0 6669if an entry is present otherwise returns 1. 6670. 6671.It Ic time Op Ar command 6672Executes 6673.Ar command 6674(which must be a simple command, not an alias, 6675a pipeline, a command list or a parenthesized command list) 6676and prints a time summary as described under the 6677.Ic time 6678variable. 6679If necessary, an extra shell is created to print the time statistic when 6680the command completes. 6681Without 6682.Ar command , 6683prints a time summary for the current shell and its 6684children. 6685.. 6686.It Ic umask Op Ar value 6687Sets the file creation mask to 6688.Ar value , 6689which is given in octal. 6690Common values for the mask are 6691002, giving all access to the group and read and execute access to others, and 6692022, giving read and execute access to the group and others. 6693Without 6694.Ar value , 6695prints the current file creation mask. 6696. 6697.It Ic unalias Ar pattern 6698Removes all aliases whose names match 6699.Ar pattern . 6700.Ql unalias * 6701thus removes all aliases. 6702It is not an error for nothing to be 6703.Ic unalias Ns 6704ed. 6705. 6706.It Ic uncomplete Ar pattern No (+) 6707Removes all completions whose names match 6708.Ar pattern . 6709.Ql uncomplete * 6710thus removes all completions. 6711It is not an error for nothing to be 6712.Ic uncomplete Ns 6713d. 6714. 6715.It Ic unhash 6716Disables use of the internal hash table to speed location of 6717executed programs. 6718. 6719.It Ic universe Ar universe No (+) 6720Sets the universe to 6721.Ar universe . 6722(Masscomp/RTU only) 6723. 6724.It Ic unlimit Oo Fl hf Oc Op Ar resource 6725Removes the limitation on 6726.Ar resource 6727or, if no 6728.Ar resource 6729is 6730specified, all 6731.Ar resource 6732limitations. 6733With 6734.Fl h , 6735the corresponding hard limits are removed. 6736Only the super-user may do this. 6737Note that 6738.Ic unlimit 6739may not exit successful, since most systems 6740do not allow 6741.Ic descriptors 6742to be unlimited. 6743With 6744.Fl f 6745errors are ignored. 6746. 6747.It Ic unset Ar pattern 6748Removes all variables whose names match 6749.Ar pattern , 6750unless they are read-only. 6751.Ql unset * 6752thus removes all variables unless they are read-only; 6753this is a bad idea. 6754It is not an error for nothing to be 6755.Ic unset . 6756. 6757.It Ic unsetenv Ar pattern 6758Removes all environment variables whose names match 6759.Ar pattern . 6760.Ql unsetenv * 6761thus removes all environment variables; 6762this is a bad idea. 6763It is not an error for nothing to be 6764.Ar unsetenv Ns 6765ed. 6766. 6767.It Ic ver Oo Ar systype Oo Ar command Oc Oc No (+) 6768Without arguments, prints 6769.Ev SYSTYPE . 6770With 6771.Ar systype , 6772sets 6773.Ev SYSTYPE 6774to 6775.Ar systype . 6776With 6777.Ar systype 6778and 6779.Ar command , 6780executes 6781.Ar command 6782under 6783.Ar systype . 6784.Ar systype 6785may be 6786.Ql bsd4.3 6787or 6788.Ql sys5.3 . 6789(Domain/OS only) 6790. 6791.It Ic wait 6792The shell waits for all background jobs. 6793If the shell is interactive, an 6794interrupt will disrupt the wait and cause the shell to print the names and job 6795numbers of all outstanding jobs. 6796. 6797.It Ic warp Ar universe No (+) 6798Sets the universe to 6799.Ar universe . 6800(Convex/OS only) 6801. 6802.It Ic watchlog No (+) 6803An alternate name for the 6804.Ic log 6805builtin command (q.v.). 6806Available only if the shell was so compiled; 6807see the 6808.Ic version 6809shell variable. 6810. 6811.It Ic where Ar command No (+) 6812Reports all known instances of 6813.Ar command , 6814including aliases, builtins and 6815executables in 6816.Ic path . 6817. 6818.It Ic which Ar command No (+) 6819Displays the command that will be executed by the shell after substitutions, 6820.Ic path 6821searching, etc. 6822The builtin command is just like 6823.Xr which 1 , 6824but it correctly reports 6825.Nm 6826aliases and builtins and is 10 to 100 times faster. 6827See also the 6828.Ic which-command 6829editor command. 6830. 6831.El 6832.Pp 6833.Bl -tag -width 8n -compact 6834.Pp 6835. 6836.It Ic while Cm \&( Ns Ar expr Ns Cm \&) 6837.It Ic \&... 6838.It Ic end 6839Executes the commands between the 6840.Ic while 6841and the matching 6842.Ic end 6843while 6844.Ar expr 6845(an expression, as described under 6846.Sx Expressions ) 6847evaluates non-zero. 6848.Ic while 6849and 6850.Ic end 6851must appear alone on their input lines. 6852.Ic break 6853and 6854.Ic continue 6855may be used to terminate or continue the 6856loop prematurely. 6857If the input is a terminal, the user is prompted the first time 6858through the loop as with 6859.Ic foreach . 6860.El 6861. 6862.Ss "Special aliases (+)" 6863If set, each of these aliases executes automatically at the indicated time. 6864They are all initially undefined. 6865.Pp 6866Supported special aliases are: 6867.Pp 6868.Bl -tag -width 8n 6869. 6870.It Ic beepcmd 6871Runs when the shell wants to ring the terminal bell. 6872. 6873.It Ic cwdcmd 6874Runs after every change of working directory. 6875For example, if the user is 6876working on an X window system using 6877.Xr xterm 1 6878and a re-parenting window 6879manager that supports title bars such as 6880.Xr twm 1 6881and does 6882.Bd -literal -offset indent 6883> alias cwdcmd 'echo \-n "^[]2;${HOST}:$cwd ^G"' 6884.Ed 6885.Pp 6886then the shell will change the title of the running 6887.Xr xterm 1 6888to be the name of the host, a colon, and the full current working directory. 6889A fancier way to do that is 6890.Bd -literal -offset indent 6891> alias cwdcmd 'echo \-n "^[]2;${HOST}:$cwd^G^[]1;${HOST}^G"' 6892.Ed 6893.Pp 6894This will put the hostname and working directory on the title bar but 6895only the hostname in the icon manager menu. 6896.Pp 6897Note that putting a 6898.Ic cd , 6899.Ic pushd , 6900or 6901.Ic popd 6902in 6903.Ic cwdcmd 6904may cause an infinite loop. 6905It is the author's opinion that anyone doing 6906so will get what they deserve. 6907. 6908.It Ic jobcmd 6909Runs before each command gets executed, or when the command changes state. 6910This is similar to 6911.Ic postcmd , 6912but it does not print builtins. 6913.Bd -literal -offset indent 6914> alias jobcmd 'echo \-n "^[]2\e;\e!#:q^G"' 6915.Ed 6916.Pp 6917then executing 6918.Ql vi foo.c 6919will put the command string in the xterm title bar. 6920. 6921.It Ic helpcommand 6922Invoked by the 6923.Ic run-help 6924editor command. 6925The command name for which help 6926is sought is passed as sole argument. 6927For example, if one does 6928.Bd -literal -offset indent 6929> alias helpcommand '\e!:1 --help' 6930.Ed 6931.Pp 6932then the help display of the command itself will be invoked, using the GNU 6933help calling convention. 6934Currently there is no easy way to account for various calling conventions (e.g., 6935the customary Unix 6936.Ql -h ) , 6937except by using a table of many commands. 6938. 6939.It Ic periodic 6940Runs every 6941.Ic tperiod 6942minutes. 6943This provides a convenient means for 6944checking on common but infrequent changes such as new mail. 6945For example, 6946if one does 6947.Bd -literal -offset indent 6948> set tperiod = 30 6949> alias periodic checknews 6950.Ed 6951.Pp 6952then the 6953.Xr checknews 1 6954program runs every 30 minutes. 6955If 6956.Ic periodic 6957is set but 6958.Ic tperiod 6959is unset or set to 0, 6960.Ic periodic 6961behaves like 6962.Ic precmd . 6963. 6964.It Ic precmd 6965Runs just before each prompt is printed. 6966For example, if one does 6967.Bd -literal -offset indent 6968> alias precmd date 6969.Ed 6970.Pp 6971then 6972.Xr date 1 6973runs just before the shell prompts for each command. 6974There are no limits on what 6975.Ic precmd 6976can be set to do, but discretion 6977should be used. 6978. 6979.It Ic postcmd 6980Runs before each command gets executed. 6981.Bd -literal -offset indent 6982> alias postcmd 'echo \-n "^[]2\e;\e!#:q^G"' 6983.Ed 6984.Pp 6985then executing 6986.Ql vi foo.c 6987will put the command string in the xterm title bar. 6988. 6989.It Ic shell 6990Specifies the interpreter for executable scripts which do not themselves 6991specify an interpreter. 6992The first word should be a full path name to the 6993desired interpreter (e.g., 6994.Ql /bin/csh 6995or 6996.Ql /usr/local/bin/tcsh ) . 6997. 6998.El 6999. 7000.Ss "Special shell variables" 7001The variables described in this section have special meaning to the shell. 7002.Pp 7003The shell sets 7004.Ic addsuffix , 7005.Ic argv , 7006.Ic autologout , 7007.Ic csubstnonl , 7008.Ic command , 7009.Ic echo_style , 7010.Ic edit , 7011.Ic gid , 7012.Ic group , 7013.Ic home , 7014.Ic loginsh , 7015.Ic oid , 7016.Ic path , 7017.Ic prompt , 7018.Ic prompt2 , 7019.Ic prompt3 , 7020.Ic shell , 7021.Ic shlvl , 7022.Ic tcsh , 7023.Ic term , 7024.Ic tty , 7025.Ic uid , 7026.Ic user , 7027and 7028.Ic version 7029at 7030startup; they do not change thereafter unless changed by the user. 7031The shell updates 7032.Ic cwd , 7033.Ic dirstack , 7034.Ic owd , 7035and 7036.Ic status 7037when necessary, 7038and sets 7039.Ic logout 7040on logout. 7041.Pp 7042The shell synchronizes 7043.Ic group , 7044.Ic home , 7045.Ic path , 7046.Ic shlvl , 7047.Ic term , 7048and 7049.Ic user 7050with the environment variables of the same names: 7051whenever the environment variable changes the shell changes the corresponding 7052shell variable to match (unless the shell variable is read-only) and vice 7053versa. 7054Note that although 7055.Ic cwd 7056and 7057.Ev PWD 7058have identical meanings, they 7059are not synchronized in this manner, and that the shell automatically 7060converts between the different formats of 7061.Ic path 7062and 7063.Ev PATH . 7064. 7065.Pp 7066Supported special shell variables are: 7067. 7068.Bl -tag -width 8n 7069. 7070.It Ic addsuffix No (+) 7071If set, filename completion adds 7072.Ql / 7073to the end of directories and a space 7074to the end of normal files when they are matched exactly. 7075Set by default. 7076. 7077.It Ic afsuser No (+) 7078If set, 7079.Ic autologout Ns 7080\&'s autolock feature uses its value instead of 7081the local username for kerberos authentication. 7082. 7083.It Ic ampm No (+) 7084If set, all times are shown in 12-hour AM/PM format. 7085. 7086.It Ic anyerror No (+) 7087This variable selects what is propagated to the value of the 7088.Ic status 7089variable. For more information see the description of the 7090.Ic status 7091variable below. 7092. 7093.It Ic argv 7094The arguments to the shell. 7095Positional parameters are taken from 7096.Ic argv , 7097i.e., 7098.Ql $1 7099is replaced by 7100.Ql $argv[1] , 7101etc. 7102Set by default, but usually empty in interactive shells. 7103. 7104.It Ic autocorrect No (+) 7105If set, the 7106.Ic spell-word 7107editor command is invoked automatically before 7108each completion attempt. 7109. 7110.It Ic autoexpand No (+) 7111If set, the 7112.Ic expand-history 7113editor command is invoked automatically 7114before each completion attempt. If this is set to 7115.Ql onlyhistory , 7116then 7117only history will be expanded and a second completion will expand filenames. 7118. 7119.It Ic autolist No (+) 7120If set, possibilities are listed after an ambiguous completion. 7121If set to 7122.Ql ambiguous , 7123possibilities are listed only when no new 7124characters are added by completion. 7125. 7126.It Ic autologout No (+) 7127The first word is the number of minutes of inactivity before automatic 7128logout. 7129The optional second word is the number of minutes of inactivity 7130before automatic locking. 7131When the shell automatically logs out, it prints 7132.Sq auto-logout , 7133sets the 7134variable 7135.Ic logout 7136to 7137.Ql automatic 7138and exits. 7139When the shell automatically locks, the user is required to enter their password 7140to continue working. 7141Five incorrect attempts result in automatic logout. 7142Set to 7143.Ql 60 7144(automatic logout after 60 minutes, and no locking) by default 7145in login and superuser shells, but not if the shell thinks it is running 7146under a window system (i.e., the 7147.Ev DISPLAY 7148environment variable is set), 7149the tty is a pseudo-tty (pty) or the shell was not so compiled (see the 7150.Ic version 7151shell variable). 7152Unset 7153.Ic autologout 7154or set it to 7155.Ql 0 7156to disable automatic logout. 7157See also the 7158.Ic afsuser 7159and 7160.Ic logout 7161shell variables. 7162. 7163.It Ic autorehash No (+) 7164If set, the internal hash table of the contents of the directories in the 7165.Ic path 7166variable will be recomputed if a command is not found in the hash 7167table. 7168In addition, the list of available commands will be rebuilt for each 7169command completion or spelling correction attempt if set to 7170.Ql complete 7171or 7172.Ql correct 7173respectively; if set to 7174.Ql always , 7175this will be done for both 7176cases. 7177. 7178.It Ic backslash_quote No (+) 7179.\" TODO 7180If set, backslashes (`\e') always quote 7181.Ql \e , 7182.Ql \&' , 7183and 7184.Ql \&" . 7185This may make 7186complex quoting tasks easier, but it can cause syntax errors in 7187.Xr csh 1 7188scripts. 7189. 7190.It Ic catalog 7191The file name of the message catalog. 7192If set, 7193.Nm 7194uses 7195.Sq tcsh.${catalog} 7196as a message catalog instead of 7197default 7198.Sq tcsh . 7199. 7200.It Ic cdpath 7201A list of directories in which 7202.Ic cd 7203should search for 7204subdirectories if they aren't found in the current directory. 7205. 7206.It Ic cdtohome No (+) 7207If not set, 7208.Ic cd 7209requires a directory 7210.Ar name , 7211and will not go to the 7212.Ic home 7213directory if it's omitted. 7214This is set by default. 7215. 7216.It Ic color 7217If set, it enables color display for the builtin 7218.Ic ls\-F 7219and it passes 7220.Fl \-color=auto 7221to 7222.Xr ls 1 . 7223Alternatively, it can be set to only 7224.Ic ls\-F 7225or only 7226.Ic ls 7227to enable color to only one command. 7228Setting 7229it to nothing is equivalent to setting it to 7230.Ql (ls\-F ls) . 7231. 7232.It Ic colorcat 7233If set, it enables color escape sequence for NLS message files. 7234And display colorful NLS messages. 7235. 7236.It Ic command No (+) 7237If set, the command which was passed to the shell with the 7238.Fl c 7239flag (q.v.). 7240. 7241.It Ic compat_expr No (+) 7242If set, the shell will evaluate expressions right to left, like the original 7243.Xr csh 1 . 7244. 7245.It Ic complete No (+) 7246If set to 7247.Ql igncase , 7248the completion becomes case insensitive. 7249If set to 7250.Ql enhance , 7251completion ignores case and considers 7252hyphens and underscores to be equivalent; it will also treat 7253periods, hyphens and underscores 7254.Po 7255.Ql \&. , 7256.Ql \- , 7257and 7258.Ql _ 7259.Pc 7260as word 7261separators. 7262If set to 7263.Ql Enhance , 7264completion matches uppercase and underscore 7265characters explicitly and matches lowercase and hyphens in a 7266case-insensitive manner; it will treat periods, hyphens and underscores 7267as word separators. 7268. 7269.It Ic continue No (+) 7270If set to a list of commands, the shell will continue the listed 7271commands, instead of starting a new one. 7272. 7273.It Ic continue_args No (+) 7274Same as continue, but the shell will execute: 7275.Bd -literal -offset indent 7276echo \`pwd\` $argv > ~/.<cmd>_pause; %<cmd> 7277.Ed 7278. 7279.It Ic correct No (+) 7280If set to 7281.Ql cmd , 7282commands are automatically spelling-corrected. 7283If set to 7284.Ql complete , 7285commands are automatically completed. 7286If set to 7287.Ql all , 7288the entire command line is corrected. 7289. 7290.It Ic csubstnonl No (+) 7291If set, newlines and carriage returns in command substitution are 7292replaced by spaces. 7293Set by default. 7294. 7295.It Ic cwd 7296The full pathname of the current directory. 7297See also the 7298.Ic dirstack 7299and 7300.Ic owd 7301shell variables. 7302. 7303.It Ic dextract No (+) 7304If set, 7305.Ql pushd + Ns Ar n 7306extracts the 7307.Ar n Ns 7308th directory from the directory 7309stack rather than rotating it to the top. 7310. 7311.It Ic dirsfile No (+) 7312The default location in which 7313.Ql dirs \-S 7314and 7315.Ql dirs \-L 7316look for 7317a history file. 7318If unset, 7319.Pa ~/.cshdirs 7320is used. 7321Because only 7322.Pa ~/.tcshrc 7323is normally sourced before 7324.Pa ~/.cshdirs , 7325.Ic dirsfile 7326should be set in 7327.Pa ~/.tcshrc 7328rather than 7329.Pa ~/.login . 7330. 7331.It Ic dirstack No (+) 7332An array of all the directories on the directory stack. 7333.Sq $dirstack[1] 7334is the current working directory, 7335.Sq $dirstack[2] 7336the first directory on the stack, etc. 7337Note that the current working directory is 7338.Sq $dirstack[1] 7339but 7340.Ql =0 7341in 7342directory stack substitutions, etc. 7343One can change the stack arbitrarily by setting 7344.Ic dirstack , 7345but the first element (the current working directory) is always correct. 7346See also the 7347.Ic cwd 7348and 7349.Ic owd 7350shell variables. 7351. 7352.It Ic dspmbyte No (+) 7353Has an effect only if 7354.Ql dspm 7355is listed as part of the 7356.Ic version 7357shell variable. 7358If set to 7359.Ql euc , 7360it enables display and editing EUC-kanji(Japanese) code. 7361If set to 7362.Ql sjis , 7363it enables display and editing Shift-JIS(Japanese) code. 7364If set to 7365.Ql big5 , 7366it enables display and editing Big5(Chinese) code. 7367If set to 7368.Ql utf8 , 7369it enables display and editing Utf8(Unicode) code. 7370If set to the following format, it enables display and editing of original 7371multi-byte code format: 7372.Bd -literal -offset indent 7373> set dspmbyte = 0000....(256 bytes)....0000 7374.Ed 7375.Pp 7376The table requires 7377.Em just 7378256 bytes. 7379Each character of 256 characters 7380corresponds (from left to right) to the ASCII codes 0x00, 0x01, ... 0xff. 7381Each 7382character 7383.\" (position in this table?) 7384is set to number 0,1,2 and 3. 7385Each number has the following meaning: 7386.Bl -tag -width 3n -offset indent -compact 7387.It Li 0 7388Not used for multi-byte characters. 7389.It Li 1 7390Used for the first byte of a multi-byte character. 7391.It Li 2 7392Used for the second byte of a multi-byte character. 7393.It Li 3 7394Used for both the first byte and second byte of a multi-byte character. 7395.El 7396.\" SHK: I tried my best to get the following to be grammatically correct. 7397.\" However, I still don't understand what's going on here. In the 7398.\" following example, there are three bytes, but the text seems to refer to 7399.\" each nybble as a character. What's going on here? It this 3-byte code 7400.\" in the table? The text above seems to imply that there are 256 7401.\" characters/bytes in the table. If I get some more info on this (perhaps 7402.\" a complete example), I could fix the text to be grammatically correct. 7403.\" (steve.kelem@xilinx.com 1999/09/13) 7404.Pp 7405Example: 7406.Pp 7407If set to 7408.Ql 001322 , 7409the first character (means 0x00 of the ASCII code) and 7410second character (means 0x01 of ASCII code) are set to 7411.Ql 0 . 7412Then, it is not 7413used for multi-byte characters. 7414The 3rd character (0x02) is set to 7415.Ql 1 , 7416indicating that it is used for the first byte of a multi-byte character. 7417The 4th character (0x03) is set 7418.Ql 3 . 7419It is used for both the first byte and 7420the second byte of a multi-byte character. 7421The 5th and 6th characters 7422(0x04,0x05) are set to 7423.Ql 2 , 7424indicating that they are used for the second 7425byte of a multi-byte character. 7426.Pp 7427The GNU fileutils version of ls cannot display multi-byte 7428filenames without the 7429.Fl N 7430.Pq Fl -literal 7431option. 7432If you are using 7433this version, set the second word of dspmbyte to 7434.Ql ls . 7435If not, for 7436example, 7437.Ql ls-F -l 7438cannot display multi-byte filenames. 7439.Pp 7440Note: 7441.Pp 7442This variable can only be used if KANJI and DSPMBYTE has been defined at 7443compile time. 7444. 7445.It Ic dunique No (+) 7446If set, 7447.Ic pushd 7448removes any instances of 7449.Ar name 7450from the stack before pushing it onto the stack. 7451. 7452.It Ic echo 7453If set, each command with its arguments is echoed just before it is 7454executed. 7455For non-builtin commands all expansions occur before 7456echoing. 7457Builtin commands are echoed before command and filename 7458substitution, because these substitutions are then done selectively. 7459Set by the 7460.Fl x 7461command line option. 7462. 7463.It Ic echo_style No (+) 7464The style of the 7465.Ic echo 7466builtin. 7467May be set to: 7468.Pp 7469.Bl -tag -width 4n -offset indent -compact 7470.It Li bsd 7471Don't echo a newline if the first argument is 7472.Fl n ; 7473the default for 7474.Xr csh 1 . 7475. 7476.It Li sysv 7477Recognize backslashed escape sequences in echo strings. 7478. 7479.It Li both 7480Recognize both the 7481.Fl n 7482flag and backslashed escape sequences; the default 7483for 7484.Nm . 7485. 7486.It Li none 7487Recognize neither. 7488.El 7489.Pp 7490Set by default to the local system default. 7491The BSD and System V 7492options are described in the 7493.Xr echo 1 7494man pages on the appropriate 7495systems. 7496. 7497.It Ic edit No (+) 7498If set, the command-line editor is used. 7499Set by default in interactive 7500shells. 7501. 7502.It Ic editors No (+) 7503A list of command names for the 7504.Ic run-fg-editor 7505editor command to match. 7506If not set, the 7507.Ev EDITOR 7508.Ql ( ed 7509if unset) and 7510.Ev VISUAL 7511.Ql ( vi 7512if unset) 7513environment variables will be used instead. 7514. 7515.It Ic ellipsis No (+) 7516If set, the 7517.Ql %c , 7518.Ql %. , 7519and 7520.Ql \&%C 7521prompt sequences (see the 7522.Ic prompt 7523shell variable) indicate skipped directories with an ellipsis 7524.Pq Ql \&... 7525instead of 7526.Ql /< Ns Ar skipped Ns Li > . 7527. 7528.It Ic euid No (+) 7529The user's effective user ID. 7530. 7531.It Ic euser No (+) 7532The first matching passwd entry name corresponding to the effective user ID. 7533. 7534.It Ic fignore No (+) 7535Lists file name suffixes to be ignored by completion. 7536. 7537.It Ic filec 7538In 7539.Nm , 7540completion is always used and this variable is ignored 7541by default. If 7542.Ic edit 7543is unset, then the traditional 7544.Xr csh 1 7545completion is used. 7546If set in 7547.Xr csh 1 , 7548filename completion is used. 7549. 7550.It Ic gid No (+) 7551The user's real group ID. 7552. 7553.It Ic globdot No (+) 7554If set, wild-card glob patterns will match files and directories beginning 7555with 7556.Ql \&. 7557except for 7558.Sq Pa \&. 7559and 7560.Sq Pa \&.. . 7561. 7562.It Ic globstar No (+) 7563If set, the 7564.Ql ** 7565and 7566.Ql *** 7567file glob patterns will match any string of 7568characters including 7569.Ql / 7570traversing any existing sub-directories. 7571(e.g. 7572.Ql ls **.c 7573will list all the .c files in the current directory tree). 7574If used by itself, it will match zero or more sub-directories 7575(e.g. 7576.Ql ls /usr/include/**/time.h 7577will list any file named 7578.Ql time.h 7579in the 7580.Pa /usr/include 7581directory tree; whereas 7582.Ql ls /usr/include/**time.h 7583will match any file in the 7584.Pa /usr/include 7585directory tree ending in 7586.Ql time.h ) . 7587To prevent problems with recursion, the 7588.Ql ** 7589glob-pattern will not 7590descend into a symbolic link containing a directory. 7591To override this, 7592use 7593.Ql *** . 7594. 7595.It Ic group No (+) 7596The user's group name. 7597. 7598.It Ic highlight 7599If set, the incremental search match (in 7600.Ic i-search-back 7601and 7602.Ic i-search-fwd ) 7603and the region between the mark and the cursor are 7604highlighted in reverse video. 7605.Pp 7606Highlighting requires more frequent terminal writes, which introduces extra 7607overhead. If you care about terminal performance, you may want to leave this 7608unset. 7609. 7610.It Ic histchars 7611A string value determining the characters used in 7612.Sx History substitution 7613(q.v.). 7614The first character of its value is used as 7615the history substitution character, replacing the default character 7616.Ql \&! . 7617The second character of its value replaces the character 7618.Ql ^ 7619in 7620quick substitutions. 7621. 7622.It Ic histdup No (+) 7623Controls handling of duplicate entries in the history list. 7624If set to 7625.Ql all 7626only unique history events are entered in the history list. 7627If 7628set to 7629.Ql prev 7630and the last history event is the same as the current 7631command, then the current command is not entered in the history. 7632If 7633set to 7634.Ql erase 7635and the same event is found in the history list, that 7636old event gets erased and the current one gets inserted. 7637Note that the 7638.Ql prev 7639and 7640.Ql all 7641options renumber history events so there are no gaps. 7642. 7643.It Ic histfile No (+) 7644The default location in which 7645.Ql history \-S 7646and 7647.Ql history \-L 7648look for 7649a history file. 7650If unset, 7651.Pa ~/.history 7652is used. 7653.Ic histfile 7654is 7655useful when sharing the same home directory between different machines, 7656or when saving separate histories on different terminals. 7657Because only 7658.Pa ~/.tcshrc 7659is normally sourced before 7660.Pa ~/.history , 7661.Ic histfile 7662should be set in 7663.Pa ~/.tcshrc 7664rather than 7665.Pa ~/.login . 7666. 7667.It Ic histlit No (+) 7668If set, builtin and editor commands and the 7669.Ic savehist 7670mechanism 7671use the literal (unexpanded) form of lines in the history list. 7672See 7673also the 7674.Ic toggle-literal-history 7675editor command. 7676. 7677.It Ic history 7678The first word indicates the number of history events to save. 7679The 7680optional second word (+) indicates the format in which history is 7681printed; if not given, 7682.Ql %h\et%T\et%R\en 7683is used. 7684The format sequences 7685are described below under 7686.Ic prompt ; 7687note the variable meaning of 7688.Ql \&%R . 7689Set to 7690.Ql 100 7691by default. 7692. 7693.It Ic home 7694Initialized to the home directory of the invoker. 7695The filename 7696expansion of 7697.Ql ~ 7698refers to this variable. 7699. 7700.It Ic ignoreeof 7701If set to the empty string or 7702.Ql 0 7703and the input device is a terminal, 7704the 7705.Ic end-of-file 7706command (usually generated by the user by typing 7707.Sq ^D 7708on an empty line) causes the shell to print 7709.Ql Use \&"exit\&" to leave tcsh. 7710instead of exiting. 7711This prevents the shell from accidentally 7712being killed. 7713Historically this setting exited after 26 successive 7714EOF's to avoid infinite loops. 7715If set to a number 7716.Sq Em n , 7717the shell 7718ignores 7719.Em n 7720\- 1 7721consecutive 7722.Ic end-of-file Ns 7723s and exits on the 7724.Em n Ns 7725th. 7726(+) If unset, 7727.Ql 1 7728is used, i.e., the shell exits on a 7729single 7730.Sq ^D . 7731. 7732.It Ic implicitcd No (+) 7733If set, the shell treats a directory name typed as a command as though 7734it were a request to change to that directory. 7735If set to 7736.Ic verbose , 7737the change of directory is echoed to the standard output. 7738This behavior 7739is inhibited in non-interactive shell scripts, or for command strings 7740with more than one word. 7741Changing directory takes precedence over 7742executing a like-named command, but it is done after alias 7743substitutions. 7744Tilde and variable expansions work as expected. 7745. 7746.It Ic inputmode No (+) 7747If set to 7748.Ql insert 7749or 7750.Ql overwrite , 7751puts the editor into that input mode 7752at the beginning of each line. 7753. 7754.It Ic killdup No (+) 7755Controls handling of duplicate entries in the kill ring. 7756If set to 7757.Ql all 7758only unique strings are entered in the kill ring. 7759If set to 7760.Ql prev 7761and the last killed string is the same as the current killed 7762string, then the current string is not entered in the ring. 7763If set 7764to 7765.Ql erase 7766and the same string is found in the kill ring, the old 7767string is erased and the current one is inserted. 7768. 7769.It Ic killring No (+) 7770Indicates the number of killed strings to keep in memory. 7771Set to 7772.Ql 30 7773by default. 7774If unset or set to less than 7775.Ql 2 , 7776the shell will only 7777keep the most recently killed string. 7778Strings are put in the killring by the editor commands that delete 7779(kill) strings of text, e.g. 7780.Ic backward-delete-word , 7781.Ic kill-line , 7782etc, as well as the 7783.Ic copy-region-as-kill 7784command. 7785The 7786.Ic yank 7787editor command will yank the most recently killed string 7788into the command-line, while 7789.Ic yank-pop 7790(see 7791.Sx Editor commands ) 7792can be used to yank earlier killed strings. 7793. 7794.It Ic listflags No (+) 7795If set to 7796.Ql x , 7797.Ql a , 7798or 7799.Ql A , 7800or any combination thereof (e.g., 7801.Ql xA ) , 7802they are used as flags to 7803.Ic ls\-F , 7804making it act like 7805.Ql ls \-xF , 7806.Ql ls \-Fa , 7807.Ql ls \-FA , 7808or a combination (e.g., 7809.Ql ls \-FxA ) : 7810.Ql a 7811shows all 7812files (even if they start with a 7813.Ql \&. ) , 7814.Ql A 7815shows all files but 7816.Ql \&. 7817and 7818.Ql \&.. , 7819and 7820.Ql x 7821sorts across instead of down. 7822If the second word of 7823.Ic listflags 7824is set, it is used as the path to 7825.Xr ls 1 . 7826. 7827.It Ic listjobs No (+) 7828If set, all jobs are listed when a job is suspended. 7829If set to 7830.Ql long , 7831the listing is in long format. 7832. 7833.It Ic listlinks No (+) 7834If set, the 7835.Ic ls\-F 7836builtin command shows the type of file to which 7837each symbolic link points. 7838. 7839.It Ic listmax No (+) 7840The maximum number of items which the 7841.Ic list-choices 7842editor command 7843will list without asking first. 7844. 7845.It Ic listmaxrows No (+) 7846The maximum number of rows of items which the 7847.Ic list-choices 7848editor 7849command will list without asking first. 7850. 7851.It Ic loginsh No (+) 7852Set by the shell if it is a login shell. 7853Setting or unsetting it 7854within a shell has no effect. 7855See also 7856.Ic shlvl . 7857. 7858.It Ic logout No (+) 7859Set by the shell to 7860.Ql normal 7861before a normal logout, 7862.Ql automatic 7863before 7864an automatic logout, and 7865.Ql hangup 7866if the shell was killed by a hangup 7867signal (see 7868.Sx Signal handling ) . 7869See also the 7870.Ic autologout 7871shell variable. 7872. 7873.It Ic mail 7874A list of files and directories to check for incoming mail, optionally 7875preceded by a numeric word. 7876Before each prompt, if 10 minutes have 7877passed since the last check, the shell checks each file and displays 7878.Sq You have new mail. 7879(or, if 7880.Ic mail 7881contains multiple files, 7882.Sq You have new mail in Ar name Ns \&. ) 7883if the filesize is greater than zero in size 7884and has a modification time greater than its access time. 7885.Pp 7886If you are in a login shell, then no mail file is reported unless it has 7887been modified after the time the shell has started up, to prevent 7888redundant notifications. 7889Most login programs will tell you whether or not 7890you have mail when you log in. 7891.Pp 7892If a file specified in 7893.Ic mail 7894is a directory, the shell will count each 7895file within that directory as a separate message, and will report 7896.Sq You have Ar n No mails. 7897or 7898.Sq You have Ar n No mails in Ar name Ns No \&. 7899as appropriate. 7900This functionality is provided primarily for those systems which store mail 7901in this manner, such as the Andrew Mail System. 7902.Pp 7903If the first word of 7904.Ic mail 7905is numeric it is taken as a different mail 7906checking interval, in seconds. 7907.Pp 7908Under very rare circumstances, the shell may report 7909.Sq You have mail. 7910instead 7911of 7912.Sq You have new mail. 7913. 7914.It Ic matchbeep No (+) 7915If set to 7916.Ql never , 7917completion never beeps. 7918If set to 7919.Ql nomatch , 7920it beeps only when there is no match. 7921If set to 7922.Ql ambiguous , 7923it beeps when there are multiple matches. 7924If set to 7925.Ql notunique , 7926it beeps when there is one exact and other longer matches. 7927If unset, 7928.Ql ambiguous 7929is used. 7930. 7931.It Ic nobeep No (+) 7932If set, beeping is completely disabled. 7933See also 7934.Ic visiblebell . 7935. 7936.It Ic noclobber 7937If set, restrictions are placed on output redirection to insure that files 7938are not accidentally destroyed and that 7939.Ql >> 7940redirections refer to existing 7941files, as described in the 7942.Sx Input/output 7943section. 7944If contains 7945.Ql ask , 7946an interacive confirmation is presented, rather than an 7947error. 7948If contains 7949.Ql notempty , 7950.Ql > 7951is allowed on empty files. 7952. 7953.It Ic noding 7954If set, disable the printing of 7955.Ql DING! 7956in the 7957.Ic prompt 7958time 7959specifiers at the change of hour. 7960. 7961.It Ic noglob 7962If set, 7963.Sx Filename substitution 7964and 7965.Sx Directory stack substitution 7966(q.v.) are inhibited. 7967This is most useful in shell scripts which do not deal 7968with filenames, or after a list of filenames has been obtained and further 7969expansions are not desirable. 7970. 7971.It Ic nokanji No (+) 7972If set and the shell supports Kanji (see the 7973.Ic version 7974shell variable), 7975it is disabled so that the meta key can be used. 7976. 7977.It Ic nonomatch 7978If set, a 7979.Sx Filename substitution 7980or 7981.Sx Directory stack substitution 7982(q.v.) which does not match any 7983existing files is left untouched rather than causing an error. 7984It is still an error for the substitution to be 7985malformed, e.g., 7986.Ql echo [ 7987still gives an error. 7988. 7989.It Ic nostat No (+) 7990A list of directories (or glob-patterns which match directories; see 7991.Sx Filename substitution ) 7992that should not be 7993.Xr stat 2 Ns ed 7994during a 7995completion operation. 7996This is usually used to exclude directories which 7997take too much time to 7998.Xr stat 2 , 7999for example 8000.Pa /afs . 8001. 8002.It Ic notify 8003If set, the shell announces job completions asynchronously. 8004The default is to present job completions just before printing a prompt. 8005. 8006.It Ic oid No (+) 8007The user's real organization ID. 8008(Domain/OS only) 8009. 8010.It Ic owd No (+) 8011The old working directory, equivalent to the 8012.Ql \- 8013used by 8014.Ic cd 8015and 8016.Ic pushd . 8017See also the 8018.Ic cwd 8019and 8020.Ic dirstack 8021shell variables. 8022. 8023.It Ic padhour 8024If set, enable the printing of padding '0' for hours, in 24 and 12 hour 8025formats. 8026E.g., 8027.Sq 07:45:42 8028versus 8029.Sq 7:45:42 . 8030. 8031.It Ic parseoctal 8032To retain compatibily with older versions numeric variables starting with 80330 are not interpreted as octal. Setting this variable enables proper octal 8034parsing. 8035. 8036.It Ic path 8037A list of directories in which to look for executable commands. 8038A null word specifies the current directory. 8039If there is no 8040.Ic path 8041variable then only full path names will execute. 8042.Ic path 8043is set by the shell at startup from the 8044.Ev PATH 8045environment 8046variable or, if 8047.Ev PATH 8048does not exist, to a system-dependent default 8049something like 8050.Ql (/usr/local/bin /usr/bsd /bin /usr/bin .) . 8051The shell may put 8052.Ql \&. 8053first or last in 8054.Ic path 8055or omit it entirely 8056depending on how it was compiled; see the 8057.Ic version 8058shell variable. 8059A shell which is given neither the 8060.Fl c 8061nor the 8062.Fl t 8063option 8064hashes the contents of the directories in 8065.Ic path 8066after 8067reading 8068.Pa ~/.tcshrc 8069and each time 8070.Ic path 8071is reset. 8072If one adds a new command to a directory in 8073.Ic path 8074while the shell 8075is active, one may need to do a 8076.Ic rehash 8077for the shell to find it. 8078. 8079.It Ic printexitvalue No (+) 8080If set and an interactive program exits with a non-zero status, the shell 8081prints 8082.Sq Exit Ar status . 8083. 8084.It Ic prompt 8085The string which is printed before reading each command from the terminal. 8086.Pp 8087.Ic prompt 8088may include any of the following formatting sequences (+), which 8089are replaced by the given information: 8090.Pp 8091.Bl -tag -width 4n -offset indent -compact 8092. 8093.It Li %/ 8094The current working directory. 8095. 8096.It Li %~ 8097The current working directory, but with one's home directory 8098represented by 8099.Ql ~ 8100and other users' home directories represented by 8101.Ql ~ Ns Ar user 8102as per 8103.Sx Filename substitution . 8104.Ql ~ Ns Ar user 8105substitution 8106happens only if the shell has already used 8107.Ql ~ Ns Ar user 8108in a pathname 8109in the current session. 8110. 8111.It Xo 8112.Li %c[[0] Ns Ar n Ns Li ] , 8113.Li %.[[0] Ns Ar n Ns Li ] 8114.Xc 8115The trailing component of the current working directory, or 8116.Ar n 8117trailing components if a digit 8118.Ar n 8119is given. 8120If 8121.Ar n 8122begins with 8123.Ql 0 , 8124the number of skipped components precede 8125the trailing component(s) in the format 8126.Ql /< Ns Ar skipped Ns Li >trailing . 8127If the 8128.Ic ellipsis 8129shell variable is set, skipped components 8130are represented by an ellipsis so the whole becomes 8131.Ql \&...trailing . 8132.Ql ~ 8133substitution is done as in 8134.Ql %~ 8135above, but the 8136.Ql ~ 8137component 8138is ignored when counting trailing components. 8139. 8140.It Li \&%C 8141Like 8142.Ql %c , 8143but without 8144.Ql ~ 8145substitution. 8146. 8147.It Li %h , %! , \&! 8148The current history event number. 8149. 8150.It Li \&%M 8151The full hostname. 8152. 8153.It Li %m 8154The hostname up to the first 8155.Ql \&. . 8156. 8157.It Li \&%S Pq Li %s 8158Start (stop) standout mode. 8159. 8160.It Li \&%B Pq Li %b 8161Start (stop) boldfacing mode. 8162. 8163.It Li \&%U (%u) 8164Start (stop) underline mode. 8165. 8166.It Li %t , %@ 8167The time of day in 12-hour AM/PM format. 8168. 8169.It Li \&%T 8170Like 8171.Ql %t , 8172but in 24-hour format (but see the 8173.Ic ampm 8174shell variable). 8175. 8176.It Li %p 8177The 8178.Sq precise 8179time of day in 12-hour AM/PM format, with seconds. 8180. 8181.It Li \&%P 8182Like 8183.Ql %p , 8184but in 24-hour format (but see the 8185.Ic ampm 8186shell variable). 8187. 8188.It Li \e Ns Ar c 8189.Ar c 8190is parsed as in 8191.Ic bindkey . 8192. 8193.It Li ^ Ns Ar c 8194.Ar c 8195is parsed as in 8196.Ic bindkey . 8197. 8198.It Li %% 8199A single 8200.Ql % . 8201. 8202.It Li %n 8203The user name. 8204. 8205.It Li \&%N 8206The effective user name. 8207. 8208.It Li %j 8209The number of jobs. 8210. 8211.It Li %d 8212The weekday in 8213.Sq Day 8214format. 8215. 8216.It Li \&%D 8217The day in 8218.Sq dd 8219format. 8220. 8221.It Li %w 8222The month in 8223.Sq Mon 8224format. 8225. 8226.It Li \&%W 8227The month in 8228.Sq mm 8229format. 8230. 8231.It Li %y 8232The year in 8233.Sq yy 8234format. 8235. 8236.It Li \&%Y 8237The year in 8238.Sq yyyy 8239format. 8240. 8241.It Li %l 8242The shell's tty. 8243. 8244.It Li \&%L 8245Clears from the end of the prompt to end of the display or the end of the line. 8246. 8247.It Li %$ 8248Expands the shell or environment variable name immediately after the 8249.Ql $ . 8250. 8251.It Li %# 8252.Ql > 8253(or the first character of the 8254.Ic promptchars 8255shell variable) 8256for normal users, 8257.Ql # 8258(or the second character of 8259.Ic promptchars ) 8260for the superuser. 8261. 8262.It Li %{ Ns Ar string Ns Li %} 8263Includes 8264.Ic string 8265as a literal escape sequence. 8266It should be used only to change terminal attributes and 8267should not move the cursor location. 8268This 8269cannot be the last sequence in 8270.Ic prompt . 8271. 8272.It Li %? 8273The return code of the command executed just before the prompt. 8274. 8275.It Li \&%R 8276In 8277.Ic prompt2 , 8278the status of the parser. 8279In 8280.Ic prompt3 , 8281the corrected string. 8282In 8283.Ic history , 8284the history string. 8285. 8286.El 8287. 8288.Pp 8289.Ql \&%B , 8290.Ql \&%S , 8291.Ql \&%U , 8292and 8293.Ql %{ Ns Ar string Ns Li %} 8294are available in only 8295eight-bit-clean shells; see the 8296.Ic version 8297shell variable. 8298.Pp 8299The bold, standout and underline sequences are often used to distinguish a 8300superuser shell. 8301For example, 8302.Pp 8303.\" Using Bl not Bd to allow bold formatting in the second line 8304.Bl -tag -offset indent -compact 8305.It Li > set prompt = \&"%m [%h] \&%B[%@]%b [%/] you rang? \&" 8306.It Li tut [37] Cm [2:54pm] Li [/usr/accts/sys] you rang? _ 8307.El 8308.Pp 8309If 8310.Ql %t , 8311.Ql %@ , 8312.Ql \&%T , 8313.Ql %p , 8314or 8315.Ql \&%P 8316is used, and 8317.Ic noding 8318is not set, 8319then print 8320.Sq DING! 8321on the change of hour (i.e, 8322.Sq \&:00 8323minutes) instead of 8324the actual time. 8325.Pp 8326Set by default to 8327.Ql %#\ \& 8328in interactive shells. 8329. 8330.It Ic prompt2 No (+) 8331The string with which to prompt in 8332.Ic while 8333and 8334.Ic foreach 8335loops and 8336after lines ending in 8337.Ql \e . 8338The same format sequences may be used as in 8339.Ic prompt 8340(q.v.); 8341note the variable meaning of 8342.Ql \&%R . 8343Set by default to 8344.Ql \&%R?\ \& 8345in interactive shells. 8346. 8347.It Ic prompt3 No (+) 8348The string with which to prompt when confirming automatic spelling correction. 8349The same format sequences may be used as in 8350.Ic prompt 8351(q.v.); 8352note the variable meaning of 8353.Ql \&%R . 8354Set by default to 8355.Ql CORRECT>%R (y|n|e|a)?\ \& 8356in interactive shells. 8357. 8358.It Ic promptchars No (+) 8359If set (to a two-character string), the 8360.Ql %# 8361formatting sequence in the 8362.Ic prompt 8363shell variable is replaced with the first character for 8364normal users and the second character for the superuser. 8365. 8366.It Ic pushdtohome No (+) 8367If set, 8368.Ic pushd 8369without arguments does 8370.Ql pushd ~ , 8371like 8372.Ic cd . 8373. 8374.It Ic pushdsilent No (+) 8375If set, 8376.Ic pushd 8377and 8378.Ic popd 8379do not print the directory stack. 8380. 8381.It Ic recexact No (+) 8382If set, completion completes on an exact match even if a longer match is 8383possible. 8384. 8385.It Ic recognize_only_executables No (+) 8386If set, command listing displays only files in the path that are 8387executable. 8388Slow. 8389. 8390.It Ic rmstar No (+) 8391If set, the user is prompted before 8392.Ql rm * 8393is executed. 8394. 8395.It Ic rprompt No (+) 8396The string to print on the right-hand side of the screen (after 8397the command input) when the prompt is being displayed on the left. 8398It recognizes the same formatting characters as 8399.Ic prompt . 8400It will automatically disappear and reappear as necessary, to ensure that 8401command input isn't obscured, and will appear only if the prompt, 8402command input, and itself will fit together on the first line. 8403If 8404.Ic edit 8405isn't set, then 8406.Ic rprompt 8407will be printed after 8408the prompt and before the command input. 8409. 8410.It Ic savedirs No (+) 8411If set, the shell does 8412.Ql dirs \-S 8413before exiting. 8414If the first word is set to a number, at most that many directory stack 8415entries are saved. 8416. 8417.It Ic savehist 8418If set, the shell does 8419.Ql history \-S 8420before exiting. 8421If the first word is set to a number, at most that many lines are saved. 8422(The number should be less than or equal to the number 8423.Ic history 8424entries; 8425if it is set to greater than the number of 8426.Ic history 8427settings, only 8428.Ic history 8429entries will be saved.) 8430If the second word is set to 8431.Ql merge , 8432the history list is merged with 8433the existing history file instead of replacing it (if there is one) and 8434sorted by time stamp and the most recent events are retained. 8435If the second word of 8436.Ic savehist 8437is 8438.Ql merge 8439and the third word is set to 8440.Ql lock , 8441the history file update will be serialized with other shell sessions 8442that would possibly like to merge history at exactly the same time. (+) 8443. 8444.It Ic sched No (+) 8445The format in which the 8446.Ic sched 8447builtin command prints scheduled events; 8448if not given, 8449.Ql %h\et%T\et%R\en 8450is used. 8451The format sequences are described above under 8452.Ic prompt ; 8453note the variable meaning of 8454.Ql \&%R . 8455. 8456.It Ic shell 8457The file in which the shell resides. 8458This is used in forking 8459shells to interpret files which have execute bits set, but 8460which are not executable by the system. 8461(See the description 8462of 8463.Sx "Builtin and non-builtin command execution" . ) 8464Initialized to the 8465(system-dependent) home of the shell. 8466. 8467.It Ic shlvl No (+) 8468The number of nested shells. 8469Reset to 1 in login shells. 8470See also 8471.Ic loginsh . 8472. 8473.It Ic status 8474The exit status from the last command or backquote expansion, or any 8475command in a pipeline is propagated to 8476.Ic status . 8477(This is also the 8478default 8479.Xr csh 1 8480behavior.) 8481This default does not match what POSIX mandates (to return the 8482status of the last command only). To match the POSIX behavior, you need 8483to unset 8484.Ic anyerror . 8485.Pp 8486If the 8487.Ic anyerror 8488variable is unset, the exit status of a pipeline 8489is determined only from the last command in the pipeline, and the exit 8490status of a backquote expansion is 8491.Em not 8492propagated to 8493.Ic status . 8494.Pp 8495If a command terminated abnormally, then 0200 is added to the status. 8496Builtin commands which fail return exit status 8497.Ql 1 , 8498all other builtin 8499commands return status 8500.Ql 0 . 8501. 8502.It Ic symlinks No (+) 8503Can be set to several different values to control symbolic link 8504.Pq Sq symlink 8505resolution: 8506.Pp 8507If set to 8508.Ql chase , 8509whenever the current directory changes to a directory 8510containing a symbolic link, it is expanded to the real name of the directory 8511to which the link points. 8512This does not work for the user's home directory; 8513this is a bug. 8514.Pp 8515If set to 8516.Ql ignore , 8517the shell tries to construct a current directory 8518relative to the current directory before the link was crossed. 8519This means that 8520.Ic cd Ns 8521ing through a symbolic link and then 8522.Ql cd \&.. Ns 8523ing 8524returns one to the original directory. 8525This affects only builtin commands 8526and filename completion. 8527.Pp 8528If set to 8529.Ql expand , 8530the shell tries to fix symbolic links by actually expanding 8531arguments which look like path names. 8532This affects any command, not just 8533builtins. 8534Unfortunately, this does not work for hard-to-recognize filenames, 8535such as those embedded in command options. 8536Expansion may be prevented by 8537quoting. 8538While this setting is usually the most convenient, it is sometimes 8539misleading and sometimes confusing when it fails to recognize an argument 8540which should be expanded. 8541A compromise is to use 8542.Ql ignore 8543and use the 8544editor command 8545.Ic normalize-path 8546(bound by default to 8547.Sq ^X-n ) 8548when necessary. 8549.Pp 8550Some examples are in order. 8551First, let's set up some play directories: 8552.Bd -literal -offset indent 8553> cd /tmp 8554> mkdir from from/src to 8555> ln \-s from/src to/dst 8556.Ed 8557.Pp 8558Here's the behavior with 8559.Ic symlinks 8560unset, 8561.Bd -literal -offset indent 8562> cd /tmp/to/dst; echo $cwd 8563/tmp/to/dst 8564> cd ..; echo $cwd 8565/tmp/from 8566.Ed 8567.Pp 8568here's the behavior with 8569.Ic symlinks 8570set to 8571.Ql chase , 8572.Bd -literal -offset indent 8573> cd /tmp/to/dst; echo $cwd 8574/tmp/from/src 8575> cd ..; echo $cwd 8576/tmp/from 8577.Ed 8578.Pp 8579here's the behavior with 8580.Ic symlinks 8581set to 8582.Ql ignore , 8583.Bd -literal -offset indent 8584> cd /tmp/to/dst; echo $cwd 8585/tmp/to/dst 8586> cd ..; echo $cwd 8587/tmp/to 8588.Ed 8589.Pp 8590and here's the behavior with 8591.Ic symlinks 8592set to 8593.Ql expand . 8594.Bd -literal -offset indent 8595> cd /tmp/to/dst; echo $cwd 8596/tmp/to/dst 8597> cd ..; echo $cwd 8598/tmp/to 8599> cd /tmp/to/dst; echo $cwd 8600/tmp/to/dst 8601> cd ".."; echo $cwd 8602/tmp/from 8603> /bin/echo .. 8604/tmp/to 8605> /bin/echo ".." 8606\&.. 8607.Ed 8608.Pp 8609Note that 8610.Ql expand 8611expansion 1) works just like 8612.Ql ignore 8613for builtins 8614like 8615.Ic cd , 86162) is prevented by quoting, and 3) happens before 8617filenames are passed to non-builtin commands. 8618. 8619.It Ic tcsh No (+) 8620The version number of the shell in the format 8621.Sq Ar R Ns No \&. Ns Ar VV Ns No \&. Ns Ar PP , 8622where 8623.Sq Ar R 8624is the major release number, 8625.Sq Ar VV 8626the current version, 8627and 8628.Sq Ar PP 8629the patchlevel. 8630. 8631.It Ic term 8632The terminal type. 8633Usually set in 8634.Pa ~/.login 8635as described under 8636.Sx Startup and shutdown . 8637. 8638.It Ic time 8639If set to a number, then the 8640.Ic time 8641builtin (q.v.) executes automatically 8642after each command which takes more than that many CPU seconds. 8643If there is a second word, it is used as a format string for the output 8644of the 8645.Ic time 8646builtin. 8647.Pp 8648(u) The following sequences may be used in the 8649.Ic time 8650format string: 8651.Pp 8652.Bl -tag -width 4n -offset indent -compact 8653. 8654.It Li \&%U 8655The time the process spent in user mode in cpu seconds. 8656. 8657.It Li \&%S 8658The time the process spent in kernel mode in cpu seconds. 8659. 8660.It Li \&%E 8661The elapsed (wall clock) time in seconds. 8662. 8663.It Li \&%P 8664The CPU percentage computed as (\&%U + \&%S) / \&%E. 8665. 8666.It Li \&%W 8667Number of times the process was swapped. 8668. 8669.It Li \&%X 8670The average amount in (shared) text space used in Kbytes. 8671. 8672.It Li \&%D 8673The average amount in (unshared) data/stack space used in Kbytes. 8674. 8675.It Li \&%K 8676The total space used (\&%X + \&%D) in Kbytes. 8677. 8678.It Li \&%M 8679The maximum memory the process had in use at any time in Kbytes. 8680. 8681.It Li \&%F 8682The number of major page faults (page needed to be brought from disk). 8683. 8684.It Li \&%R 8685The number of minor page faults. 8686. 8687.It Li \&%I 8688The number of input operations. 8689. 8690.It Li \&%O 8691The number of output operations. 8692. 8693.It Li %r 8694The number of socket messages received. 8695. 8696.It Li %s 8697The number of socket messages sent. 8698. 8699.It Li %k 8700The number of signals received. 8701. 8702.It Li %w 8703The number of voluntary context switches (waits). 8704. 8705.It Li %c 8706The number of involuntary context switches. 8707. 8708.El 8709.Pp 8710Only the first four sequences are supported on systems without BSD resource 8711limit functions. 8712The default time format is 8713.Ql \&%Uu \&%Ss \&%E \&%P \&%X+%Dk \&%I+%Oio \&%Fpf+%Ww 8714for 8715systems that support resource usage reporting and 8716.Ql \&%Uu \&%Ss \&%E \&%P 8717for 8718systems that do not. 8719.Pp 8720Under Sequent's DYNIX/ptx, 8721.Ql \&%X , 8722.Ql \&%D , 8723.Ql \&%K , 8724.Ql %r , 8725and 8726.Ql %s 8727are not 8728available, but the following additional sequences are: 8729.Pp 8730.Bl -tag -width 4n -offset indent -compact 8731. 8732.It Li \&%Y 8733The number of system calls performed. 8734. 8735.It Li \&%Z 8736The number of pages which are zero-filled on demand. 8737. 8738.It Li %i 8739The number of times a process's resident set size was increased by the kernel. 8740. 8741.It Li %d 8742The number of times a process's resident set size was decreased by the kernel. 8743. 8744.It Li %l 8745The number of read system calls performed. 8746. 8747.It Li %m 8748The number of write system calls performed. 8749. 8750.It Li %p 8751The number of reads from raw disk devices. 8752. 8753.It Li %q 8754The number of writes to raw disk devices. 8755. 8756.El 8757.Pp 8758and the default time format is 8759.Ql \&%Uu \&%Ss \&%E \&%P \&%I+%Oio \&%Fpf+%Ww . 8760Note that the CPU percentage can be higher than 100% on multi-processors. 8761. 8762.It Ic tperiod No (+) 8763The period, in minutes, between executions of the 8764.Ic periodic 8765special alias. 8766. 8767.It Ic tty No (+) 8768The name of the tty, or empty if not attached to one. 8769. 8770.It Ic uid No (+) 8771The user's real user ID. 8772. 8773.It Ic user 8774The user's login name. 8775. 8776.It Ic verbose 8777If set, causes the words of each 8778command to be printed, after history substitution (if any). 8779Set by the 8780.Fl v 8781command line option. 8782. 8783.It Ic version No (+) 8784The version ID stamp. 8785It contains the shell's version number (see 8786.Ic tcsh ) , 8787origin, release date, vendor, operating system and machine (see 8788.Ev VENDOR , 8789.Ev OSTYPE , 8790and 8791.Ev MACHTYPE ) 8792and a comma-separated 8793list of options which were set at compile time. 8794Options which are set by default in the distribution are noted. 8795.Pp 8796Supported 8797.Ic version 8798options include: 8799.Pp 8800.Bl -tag -width 4n -offset indent -compact 8801. 8802.It Li 8b 8803The shell is eight bit clean; default. 8804. 8805.It Li 7b 8806The shell is not eight bit clean. 8807. 8808.It Li wide 8809The shell is multibyte encoding clean (like UTF-8). 8810. 8811.It Li nls 8812The system's NLS is used; default for systems with NLS. 8813. 8814.It Li lf 8815Login shells execute 8816.Pa /etc/csh.login 8817before instead of after 8818.Pa /etc/csh.cshrc 8819and 8820.Pa ~/.login 8821before instead of after 8822.Pa ~/.tcshrc 8823and 8824.Pa ~/.history . 8825. 8826.It Li dl 8827.Ql \&. 8828is put last in 8829.Ic path 8830for security; default. 8831. 8832.It Li nd 8833.Ql \&. 8834is omitted from 8835.Ic path 8836for security. 8837. 8838.It Li vi 8839.Xr vi 1 Ns 8840\-style editing is the default rather than 8841.Xr emacs 1 Ns 8842\-style. 8843. 8844.It Li dtr 8845Login shells drop DTR when exiting. 8846. 8847.It Li bye 8848.Ic bye 8849is a synonym for 8850.Ic logout 8851and 8852.Ic log 8853is an alternate name for 8854.Ic watchlog . 8855. 8856.It Li al 8857.Ic autologout 8858is enabled; default. 8859. 8860.It Li kan 8861Kanji is used if appropriate according to locale settings, 8862unless the 8863.Ic nokanji 8864shell variable is set. 8865. 8866.It Li sm 8867The system's 8868.Xr malloc 3 8869is used. 8870. 8871.It Li hb 8872The 8873.Ql #!<program> <args> 8874convention is emulated when executing shell scripts. 8875. 8876.It Li ng 8877The 8878.Ic newgrp 8879builtin is available. 8880. 8881.It Li rh 8882The shell attempts to set the 8883.Ev REMOTEHOST 8884environment variable. 8885. 8886.It Li afs 8887The shell verifies your password with the kerberos server if local 8888authentication fails. 8889The 8890.Ic afsuser 8891shell variable or the 8892.Ev AFSUSER 8893environment variable override your local username if set. 8894. 8895.El 8896.Pp 8897An administrator may enter additional strings to indicate differences 8898in the local version. 8899. 8900.It Ic vimode No (+) 8901If unset, various key bindings change behavior to be more 8902.Xr emacs 1 Ns 8903\-style: 8904word boundaries are determined by 8905.Ic wordchars 8906versus other characters. 8907.Pp 8908If set, various key bindings change behavior to be more 8909.Xr vi 1 Ns 8910\-style: 8911word boundaries are determined by 8912.Ic wordchars 8913versus whitespace 8914versus other characters; 8915cursor behavior depends upon current vi mode (command, delete, insert, replace). 8916.Pp 8917This variable is unset by 8918.Ic bindkey Fl e 8919and 8920set by 8921.Ic bindkey Fl v . 8922.Ic vimode 8923may be explicitly set or unset by the user after those 8924.Ic bindkey 8925operations if required. 8926. 8927.It Ic visiblebell No (+) 8928If set, a screen flash is used rather than the audible bell. 8929See also 8930.Ic nobeep . 8931. 8932.It Ic watch No (+) 8933A list of user/terminal pairs to watch for logins and logouts. 8934If either the user is 8935.Ql any 8936all terminals are watched for the given user 8937and vice versa. 8938Setting 8939.Ic watch 8940to 8941.Ql (any any) 8942watches all users and terminals. 8943For example, 8944.Bd -literal -offset indent 8945set watch = (george ttyd1 any console $user any) 8946.Ed 8947.Pp 8948reports activity of the user 8949.Ql george 8950on 8951.Ql ttyd1 , 8952any user on the console, and 8953oneself (or a trespasser) on any terminal. 8954.Pp 8955Logins and logouts are checked every 10 minutes by default, but the first 8956word of 8957.Ic watch 8958can be set to a number to check every so many minutes. 8959For example, 8960.Bd -literal -offset indent 8961set watch = (1 any any) 8962.Ed 8963.Pp 8964reports any login/logout once every minute. 8965For the impatient, the 8966.Ic log 8967builtin command triggers a 8968.Ic watch 8969report at any time. 8970All current logins 8971are reported (as with the 8972.Ic log 8973builtin) when 8974.Ic watch 8975is first set. 8976.Pp 8977The 8978.Ic who 8979shell variable controls the format of 8980.Ic watch 8981reports. 8982. 8983.It Ic who No (+) 8984The format string for 8985.Ic watch 8986messages. 8987The following sequences 8988are replaced by the given information: 8989.Pp 8990.Bl -tag -width 4n -offset indent -compact 8991. 8992.It Li %n 8993The name of the user who logged in/out. 8994. 8995.It Li %a 8996The observed action, i.e., 8997.Sq logged on , 8998.Sq logged off , 8999or 9000.Sq replaced Ar olduser No on . 9001. 9002.It Li %l 9003The terminal (tty) on which the user logged in/out. 9004. 9005.It Li \&%M 9006The full hostname of the remote host, or 9007.Sq local 9008if the login/logout was 9009from the local host. 9010. 9011.It Li %m 9012The hostname of the remote host up to the first 9013.Sq \&. . 9014The full name is printed if it is an IP address or an X Window System display. 9015. 9016.El 9017.Pp 9018.Ql \&%M 9019and 9020.Ql %m 9021are available on only systems that store the remote hostname in 9022.Pa /etc/utmp . 9023If unset, 9024.Ql %n has %a %l from %m. 9025is used, or 9026.Ql %n has %a %l. 9027on systems 9028which don't store the remote hostname. 9029. 9030.It Ic wordchars No (+) 9031A list of non-alphanumeric characters to be considered part of a word by the 9032.Ic forward-word , 9033.Ic backward-word , 9034etc., editor commands. 9035If unset, the default value is determined based on the state of 9036.Ic vimode : 9037if 9038.Ic vimode 9039is unset, 9040.Ql *?_\-.[]~= 9041is used as the default; 9042if 9043.Ic vimode 9044is set, 9045.Ql _ 9046is used as the default. 9047. 9048.El 9049. 9050.Sh ENVIRONMENT 9051.Bl -tag -width 8n 9052. 9053.It Ev AFSUSER No (+) 9054Equivalent to the 9055.Ic afsuser 9056shell variable. 9057. 9058.It Ev COMMAND_LINE 9059Set by 9060.Nm 9061to the current command line when invoking programs 9062for the 9063.Ic complete 9064.Ar list 9065mode 9066.Ql \`...\` . 9067See 9068.Ic complete 9069in 9070.Sq Builtin commands . 9071. 9072.It Ev COLUMNS 9073The number of columns in the terminal. 9074See 9075.Sx Terminal management . 9076. 9077.It Ev DISPLAY 9078Used by X Window System (see 9079.Xr X 1 ) . 9080If set, the shell does not set 9081.Ic autologout 9082(q.v.). 9083. 9084.It Ev EDITOR 9085The pathname to a default editor. 9086Used by the 9087.Ic run-fg-editor 9088editor command if the 9089the 9090.Ic editors 9091shell variable is unset. 9092See also the 9093.Ev VISUAL 9094environment variable. 9095. 9096.It Ev GROUP No (+) 9097Equivalent to the 9098.Ic group 9099shell variable. 9100. 9101.It Ev HOME 9102Equivalent to the 9103.Ic home 9104shell variable. 9105. 9106.It Ev HOST No (+) 9107Initialized to the name of the machine on which the shell 9108is running, as determined by the 9109.Xr gethostname 2 9110system call. 9111. 9112.It Ev HOSTTYPE No (+) 9113Initialized to the type of machine on which the shell 9114is running, as determined at compile time. 9115This variable is obsolete and 9116will be removed in a future version. 9117. 9118.It Ev HPATH No (+) 9119A colon-separated list of directories in which the 9120.Ic run-help 9121editor 9122command looks for command documentation. 9123. 9124.It Ev LANG 9125Gives the preferred character environment. 9126See 9127.Sx Native Language System support . 9128. 9129.It Ev LC_CTYPE 9130If set, only ctype character handling is changed. 9131See 9132.Sx Native Language System support . 9133. 9134.It Ev LINES 9135The number of lines in the terminal. 9136See 9137.Sx Terminal management . 9138. 9139.It Ev LS_COLORS 9140The format of this variable is reminiscent of the 9141.Xr termcap 5 9142file format; a colon-separated list of expressions of the form 9143.Li \&" Ns Ar xx Ns Li = Ns Ar string Ns Li \&" , 9144where 9145.Li \&" Ns Ar xx Ns Li \&" 9146is a two-character variable name. 9147.Pp 9148The 9149variables with their associated defaults are: 9150.Pp 9151.Bl -column -offset indent "Li XX" "Li XXXXX" 20n 9152. 9153.It Li no Ta Li 0 Ta Normal (non-filename) text. 9154. 9155.It Li fi Ta Li 0 Ta Regular file. 9156. 9157.It Li di Ta Li 01;34 Ta Directory. 9158. 9159.It Li ln Ta Li 01;36 Ta Symbolic link. 9160. 9161.It Li pi Ta Li 33 Ta Named pipe (FIFO). 9162. 9163.It Li so Ta Li 01;35 Ta Socket. 9164. 9165.It Li do Ta Li 01;35 Ta Door. 9166. 9167.It Li bd Ta Li 01;33 Ta Block device. 9168. 9169.It Li cd Ta Li 01;32 Ta Character device. 9170. 9171.It Li ex Ta Li 01;32 Ta Executable file. 9172. 9173.It Li mi Ta (none) Ta Missing file (defaults to Li fi Ns ) . 9174. 9175.It Li or Ta (none) Ta Orphaned symbolic link (defaults to Li ln Ns ) . 9176. 9177.It Li lc Ta Li ^[[ Ta Left code. 9178. 9179.It Li rc Ta Li m Ta Right code. 9180. 9181.It Li ec Ta (none) Ta End code (replaces Li lc Ns + Ns Li no Ns + Ns Li rc Ns ) . 9182. 9183.El 9184.Pp 9185You need to include only the variables you want to change from 9186the default. 9187.Pp 9188File names can also be colorized based on filename extension. 9189This is specified in the 9190.Ev LS_COLORS 9191variable using the syntax 9192.Li \&"* Ns Ar ext Ns Li = Ns Ar string Ns Li \&" . 9193For example, using ISO 6429 codes, to color 9194all C\-language source files blue you would specify 9195.Li \&"*.c=34\&" . 9196This would color all files ending in 9197.Ql .c 9198in blue (34) color. 9199.Pp 9200Control characters can be written either in C\-style\-escaped 9201notation, or in stty\-like ^\-notation. 9202The C\-style notation 9203adds 9204.Ql ^[ 9205for Escape, 9206.Ql \_ 9207for a normal space character, 9208and 9209.Ql \&? 9210for Delete. 9211In addition, the 9212.Ql ^[ 9213escape character 9214can be used to override the default interpretation of 9215.Ql ^[ , 9216.Ql ^ , 9217.Ql \&: , 9218and 9219.Ql = . 9220.Pp 9221Each file will be written as 9222.Ql <lc> <color-code> <rc> <filename> <ec> . 9223If the 9224.Ql <ec> 9225code is undefined, the sequence 9226.Ql <lc> <no> <rc> 9227will be used instead. 9228This is generally more convenient 9229to use, but less general. 9230The left, right and end codes are 9231provided so you don't have to type common parts over and over 9232again and to support weird terminals; you will generally not 9233need to change them at all unless your terminal does not use 9234ISO 6429 color sequences but a different system. 9235.Pp 9236If your terminal does use ISO 6429 color codes, you can 9237compose the type codes (i.e., all except the 9238.Ql lc , 9239.Ql rc , 9240and 9241.Ql ec 9242codes) from numerical commands separated by semicolons. 9243.Pp 9244The 9245most common commands are: 9246.Pp 9247.Bl -tag -width 4n -offset indent -compact 9248. 9249.It Li 0 9250To restore default color. 9251. 9252.It Li 1 9253For brighter colors. 9254. 9255.It Li 4 9256For underlined text. 9257. 9258.It Li 5 9259For flashing text. 9260. 9261.It Li 30 9262For black foreground. 9263. 9264.It Li 31 9265For red foreground. 9266. 9267.It Li 32 9268For green foreground. 9269. 9270.It Li 33 9271For yellow (or brown) foreground. 9272. 9273.It Li 34 9274For blue foreground. 9275. 9276.It Li 35 9277For purple foreground. 9278. 9279.It Li 36 9280For cyan foreground. 9281. 9282.It Li 37 9283For white (or gray) foreground. 9284. 9285.It Li 40 9286For black background. 9287. 9288.It Li 41 9289For red background. 9290. 9291.It Li 42 9292For green background. 9293. 9294.It Li 43 9295For yellow (or brown) background. 9296. 9297.It Li 44 9298For blue background. 9299. 9300.It Li 45 9301For purple background. 9302. 9303.It Li 46 9304For cyan background. 9305. 9306.It Li 47 9307For white (or gray) background. 9308. 9309.El 9310.Pp 9311Not all commands will work on all systems or display devices. 9312.Pp 9313A few terminal programs do not recognize the default end code 9314properly. 9315If all text gets colorized after you do a directory 9316listing, try changing the 9317.Ql no 9318and 9319.Ql fi 9320codes from 0 to the 9321numerical codes for your standard fore- and background colors. 9322.Pp 9323For symbolic links the 9324.Ql ln 9325keyword can be set to 9326.Ql target , 9327which makes 9328the file color the same as the color of the link target. 9329. 9330.It Ev MACHTYPE No (+) 9331The machine type (microprocessor class or machine model), as determined at compile time. 9332. 9333.It Ev NOREBIND No (+) 9334If set, printable characters are not rebound to 9335.Ic self-insert-command . 9336See 9337.Sx Native Language System support . 9338. 9339.It Ev OSTYPE No (+) 9340The operating system, as determined at compile time. 9341. 9342.It Ev PATH 9343A colon-separated list of directories in which to look for executables. 9344Equivalent to the 9345.Ic path 9346shell variable, but in a different format. 9347. 9348.It Ev PWD No (+) 9349Equivalent to the 9350.Ic cwd 9351shell variable, but not synchronized to it; 9352updated only after an actual directory change. 9353. 9354.It Ev REMOTEHOST No (+) 9355The host from which the user has logged in remotely, if this is the case and 9356the shell is able to determine it. 9357Set only if the shell was so compiled; 9358see the 9359.Ic version 9360shell variable. 9361. 9362.It Ev SHLVL No (+) 9363Equivalent to the 9364.Ic shlvl 9365shell variable. 9366. 9367.It Ev SYSTYPE No (+) 9368The current system type. 9369(Domain/OS only) 9370. 9371.It Ev TERM 9372Equivalent to the 9373.Ic term 9374shell variable. 9375. 9376.It Ev TERMCAP 9377The terminal capability string. 9378See 9379.Sx Terminal management . 9380. 9381.It Ev USER 9382Equivalent to the 9383.Ic user 9384shell variable. 9385. 9386.It Ev VENDOR No (+) 9387The vendor, as determined at compile time. 9388. 9389.It Ev VISUAL 9390The pathname to a default full-screen editor. 9391Used by the 9392.Ic run-fg-editor 9393editor command if the 9394the 9395.Ic editors 9396shell variable is unset. 9397See also the 9398.Ev EDITOR 9399environment variable. 9400. 9401.El 9402. 9403.Sh FILES 9404.Bl -tag -width 8n 9405. 9406.It Pa /etc/csh.cshrc 9407Read first by every shell. 9408ConvexOS, Stellix and Intel use 9409.Pa /etc/cshrc 9410and 9411NeXTs use 9412.Pa /etc/cshrc.std . 9413A/UX, AMIX, Cray and IRIX have no equivalent in 9414.Xr csh 1 , 9415but read this file in 9416.Nm 9417anyway. 9418Solaris 2.x does not have it either, but 9419.Nm 9420reads 9421.Pa /etc/.cshrc . 9422(+) 9423. 9424.It Pa /etc/csh.login 9425Read by login shells after 9426.Pa /etc/csh.cshrc . 9427ConvexOS, Stellix and Intel use 9428.Pa /etc/login , 9429NeXTs use 9430.Pa /etc/login.std , 9431Solaris 2.x uses 9432.Pa /etc/.login 9433and 9434A/UX, AMIX, Cray and IRIX use 9435.Pa /etc/cshrc . 9436. 9437.It Pa ~/.tcshrc No (+) 9438Read by every shell after 9439.Pa /etc/csh.cshrc 9440or its equivalent. 9441. 9442.It Pa ~/.cshrc 9443Read by every shell, if 9444.Pa ~/.tcshrc 9445doesn't exist, 9446after 9447.Pa /etc/csh.cshrc 9448or its equivalent. 9449This manual uses 9450.Sq Pa ~/.tcshrc 9451to mean 9452.Do 9453.Pa ~/.tcshrc 9454or, 9455if 9456.Pa ~/.tcshrc 9457is not found, 9458.Pa ~/.cshrc 9459.Dc . 9460. 9461.It Pa ~/.history 9462Read by login shells after 9463.Pa ~/.tcshrc 9464if 9465.Ic savehist 9466is set, but see also 9467.Ic histfile . 9468. 9469.It Pa ~/.login 9470Read by login shells after 9471.Pa ~/.tcshrc 9472or 9473.Pa ~/.history . 9474The shell may be compiled to read 9475.Pa ~/.login 9476before instead of after 9477.Pa ~/.tcshrc 9478and 9479.Pa ~/.history ; 9480see the 9481.Ic version 9482shell variable. 9483. 9484.It Pa ~/.cshdirs No (+) 9485Read by login shells after 9486.Pa ~/.login 9487if 9488.Ic savedirs 9489is set, but see also 9490.Ic dirsfile . 9491. 9492.It Pa /etc/csh.logout 9493Read by login shells at logout. 9494ConvexOS, Stellix and Intel use 9495.Pa /etc/logout 9496and 9497NeXTs use 9498.Pa /etc/logout.std . 9499A/UX, AMIX, Cray and IRIX have no equivalent in 9500.Xr csh 1 , 9501but read this file in 9502.Nm 9503anyway. 9504Solaris 2.x does not have it either, but 9505.Nm 9506reads 9507.Pa /etc/.logout . 9508(+) 9509. 9510.It Pa ~/.logout 9511Read by login shells at logout after 9512.Pa /etc/csh.logout 9513or its equivalent. 9514. 9515.It Pa /bin/sh 9516Used to interpret shell scripts not starting with a 9517.Ql # . 9518. 9519.It Pa /tmp/sh* 9520Temporary file for 9521.Ql << . 9522. 9523.It Pa /etc/passwd 9524Source of home directories for 9525.Sq ~name 9526substitutions. 9527. 9528.El 9529.Pp 9530The order in which startup files are read may differ if the shell was so 9531compiled; see 9532.Sx Startup and shutdown 9533and the 9534.Ic version 9535shell variable. 9536. 9537.Sh "NEW FEATURES (+)" 9538This manual describes 9539.Nm 9540as a single entity, 9541but experienced 9542.Xr csh 1 9543users will want to pay special attention to 9544.Nm Ns 9545\&'s new features. 9546.Pp 9547A command-line editor, which supports 9548.Xr emacs 1 Ns 9549\-style 9550or 9551.Xr vi 1 Ns 9552\-style key bindings. 9553See 9554.Sx The command-line editor 9555and 9556.Sx Editor commands . 9557.Pp 9558Programmable, interactive word completion and listing. 9559See 9560.Sx Completion and listing 9561and the 9562.Ic complete 9563and 9564.Ic uncomplete 9565builtin commands. 9566.Pp 9567.Sx Spelling correction 9568(q.v.) of filenames, commands and variables. 9569.Pp 9570.Sx Editor commands 9571(q.v.) which perform other useful functions in the middle of 9572typed commands, including documentation lookup 9573.Ic ( run-help ) , 9574quick editor restarting 9575.Ic ( run-fg-editor ) , 9576and 9577command resolution 9578.Ic ( which-command ) . 9579.Pp 9580An enhanced history mechanism. 9581Events in the history list are time-stamped. 9582See also the 9583.Ic history 9584command and its associated shell variables, 9585the previously undocumented 9586.Ql # 9587event specifier and new modifiers 9588under 9589.Sx History substitution , 9590the 9591.Ic down-history , 9592.Ic expand-history , 9593.Ic history-search-backward , 9594.Ic history-search-forward , 9595.Ic i-search-back , 9596.Ic i-search-fwd , 9597.Ic toggle-literal-history , 9598.Ic vi-search-back , 9599.Ic vi-search-fwd , 9600and 9601.Ic up-history 9602editor commands 9603and the 9604.Ic histlit 9605shell variable. 9606.Pp 9607Enhanced directory parsing and directory stack handling. 9608See the 9609.Ic cd , 9610.Ic pushd , 9611.Ic popd , 9612and 9613.Ic dirs 9614commands and their associated 9615shell variables, the description of 9616.Sx Directory stack substitution , 9617the 9618.Ic dirstack , 9619.Ic owd , 9620and 9621.Ic symlinks 9622shell variables and 9623the 9624.Ic normalize-command 9625and 9626.Ic normalize-path 9627editor commands. 9628.Pp 9629Negation in glob-patterns. 9630See 9631.Sx Filename substitution . 9632.Pp 9633New 9634.Sx File inquiry operators 9635(q.v.) and a 9636.Ic filetest 9637builtin which uses them. 9638.Pp 9639A variety of 9640.Sx Automatic, periodic and timed events 9641(q.v.) including 9642scheduled events, special aliases, automatic logout and terminal locking, 9643command timing and watching for logins and logouts. 9644.Pp 9645Support for the Native Language System 9646(see 9647.Sx Native Language System support ) , 9648OS variant features 9649(see 9650.Sx OS variant support 9651and the 9652.Ic echo_style 9653shell variable) 9654and system-dependent file locations (see 9655.Sx FILES ) . 9656.Pp 9657Extensive terminal-management capabilities. 9658See 9659.Sx Terminal management . 9660.Pp 9661New builtin commands including 9662.Ic builtins , 9663.Ic hup , 9664.Ic ls\-F , 9665.Ic newgrp , 9666.Ic printenv , 9667.Ic which , 9668and 9669.Ic where 9670(q.v.). 9671.Pp 9672New variables that make useful information easily available to the shell. 9673See the 9674.Ic gid , 9675.Ic loginsh , 9676.Ic oid , 9677.Ic shlvl , 9678.Ic tcsh , 9679.Ic tty , 9680.Ic uid , 9681and 9682.Ic version 9683shell variables and the 9684.Ev HOST , 9685.Ev REMOTEHOST , 9686.Ev VENDOR , 9687.Ev OSTYPE , 9688and 9689.Ev MACHTYPE 9690environment 9691variables. 9692.Pp 9693A new syntax for including useful information in the prompt string 9694(see 9695.Ic prompt ) , 9696and special prompts for loops and spelling correction 9697(see 9698.Ic prompt2 9699and 9700.Ic prompt3 ) . 9701.Pp 9702Read-only variables. 9703See 9704.Sx Variable substitution . 9705. 9706.Sh BUGS 9707When a suspended command is restarted, the shell prints the directory 9708it started in if this is different from the current directory. 9709This can 9710be misleading (i.e., wrong) as the job may have changed directories internally. 9711.Pp 9712Shell builtin functions are not stoppable/restartable. 9713Command sequences 9714of the form 9715.Ql a \&; b \&; c 9716are also not handled gracefully when stopping is 9717attempted. 9718If you suspend 9719.Ql b , 9720the shell will then immediately execute 9721.Ql c . 9722This is especially noticeable if this expansion results from an 9723.Ic alias . 9724It suffices to place the sequence of commands in 9725.Ql () Ns 9726\&'s to force it 9727to a subshell, i.e., 9728.Ql \&( a \&; b \&; c \&) . 9729.Pp 9730Control over tty output after processes are started is primitive; perhaps 9731this will inspire someone to work on a good virtual terminal interface. 9732In a virtual terminal interface much more interesting things could be 9733done with output control. 9734.Pp 9735Alias substitution is most often used to clumsily simulate shell procedures; 9736shell procedures should be provided rather than aliases. 9737.Pp 9738Control structures should be parsed rather than being recognized as 9739built-in commands. 9740This would allow control commands to be placed anywhere, 9741to be combined with 9742.Ql | , 9743and to be used with 9744.Ql & 9745and 9746.Ql \&; 9747metasyntax. 9748.Pp 9749.Ic foreach 9750doesn't ignore here documents when looking for its 9751.Ic end . 9752.Pp 9753It should be possible to use the 9754.Ql \&: 9755modifiers on the output of command 9756substitutions. 9757.Pp 9758The screen update for lines longer than the screen width is very poor 9759if the terminal cannot move the cursor up (i.e., terminal type 9760.Ql dumb ) . 9761.Pp 9762.Ev HPATH 9763and 9764.Ev NOREBIND 9765don't need to be environment variables. 9766.Pp 9767Glob-patterns which do not use 9768.Ql \&? , 9769.Ql * , 9770or 9771.Ql [] , 9772or which use 9773.Ql {} 9774or 9775.Ql ~ 9776are not negated correctly. 9777.Pp 9778The single-command form of 9779.Ic if 9780does output redirection even if 9781the expression is false and the command is not executed. 9782.Pp 9783.Ic ls\-F 9784includes file identification characters when sorting filenames 9785and does not handle control characters in filenames well. 9786It cannot be 9787interrupted. 9788.Pp 9789Command substitution supports multiple commands and conditions, but not 9790cycles or backward 9791.Ic goto Ns 9792s. 9793.Pp 9794Report bugs at 9795.Lk https://bugs.astron.com/ 9796preferably with fixes. 9797If you want to 9798help maintain and test tcsh, add yourself to the mailing list in 9799.Lk https://mailman.astron.com/ 9800. 9801.Sh THE T IN TCSH 9802In 1964, DEC produced the PDP-6. 9803The PDP-10 was a later re-implementation. 9804It 9805was re-christened the DECsystem-10 in 1970 or so when DEC brought out the 9806second model, the KI10. 9807.Pp 9808TENEX was created at Bolt, Beranek & Newman (a Cambridge, Massachusetts 9809think tank) in 98101972 as an experiment in demand-paged virtual memory operating systems. 9811They 9812built a new pager for the DEC PDP-10 and created the OS to go with it. 9813It was 9814extremely successful in academia. 9815.Pp 9816In 1975, DEC brought out a new model of the PDP-10, the KL10; they intended to 9817have only a version of TENEX, which they had licensed from BBN, for the new 9818box. 9819They called their version TOPS-20 (their capitalization is trademarked). 9820A lot of TOPS-10 users (`The OPerating System for PDP-10') objected; thus DEC 9821found themselves supporting two incompatible systems on the same hardware--but 9822then there were 6 on the PDP-11! 9823.Pp 9824TENEX, and TOPS-20 to version 3, had command completion 9825via a user-code-level subroutine library called ULTCMD. 9826With version 3, DEC 9827moved all that capability and more into the monitor (`kernel' for you Unix 9828types), accessed by the COMND% JSYS (`Jump to SYStem' instruction, the 9829supervisor call mechanism [are my IBM roots also showing?]). 9830.Pp 9831The creator of tcsh was impressed by this feature and several others of TENEX 9832and TOPS-20, and created a version of csh which mimicked them. 9833. 9834.Sh LIMITATIONS 9835The system limits argument lists to ARG_MAX characters. 9836.Pp 9837The number of arguments to a command which involves filename expansion is 9838limited to 1/6th the number of characters allowed in an argument list. 9839.Pp 9840Command substitutions may substitute no more characters than are allowed in 9841an argument list. 9842.Pp 9843To detect looping, the shell restricts the number of 9844.Ic alias 9845substitutions on a single line to 20. 9846. 9847.Sh "SEE ALSO" 9848.Xr csh 1 , 9849.Xr emacs 1 , 9850.Xr ls 1 , 9851.Xr newgrp 1 , 9852.Xr sh 1 , 9853.Xr setpath 1 , 9854.Xr stty 1 , 9855.Xr su 1 , 9856.Xr tset 1 , 9857.Xr vi 1 , 9858.Xr x 1 , 9859.Xr access 2 , 9860.Xr execve 2 , 9861.Xr fork 2 , 9862.Xr killpg 2 , 9863.Xr pipe 2 , 9864.Xr setrlimit 2 , 9865.Xr sigvec 2 , 9866.Xr stat 2 , 9867.Xr umask 2 , 9868.Xr vfork 2 , 9869.Xr wait 2 , 9870.Xr malloc 3 , 9871.Xr setlocale 3 , 9872.Xr tty 4 , 9873.Xr a.out 5 , 9874.Xr termcap 5 , 9875.Xr environ 7 , 9876.Xr termio 7 , 9877.Em Introduction to the C Shell 9878. 9879.Sh VERSION 9880.\" UPDATE NEXT LINE FOR RELEASE 9881This manual documents tcsh 6.24.02 (Astron) 2022-11-24. 9882. 9883.Sh AUTHORS 9884. 9885.Bl -tag -width 2n -compact 9886. 9887.It William Joy 9888Original author of 9889.Xr csh 1 9890. 9891.It J.E. Kulp, IIASA, Laxenburg, Austria 9892Job control and directory stack features 9893. 9894.It Ken Greer, HP Labs, 1981 9895File name completion 9896. 9897.It Mike Ellis, Fairchild, 1983 9898Command name recognition/completion 9899. 9900.It Paul Placeway, Ohio State CIS Dept., 1983-1993 9901Command line editor, prompt routines, new glob syntax and numerous fixes 9902and speedups 9903. 9904.It Karl Kleinpaste, CCI 1983-4 9905Special aliases, directory stack extraction stuff, login/logout watch, 9906scheduled events, and the idea of the new prompt format 9907. 9908.It Rayan Zachariassen, University of Toronto, 1984 9909.Ic ls\-F 9910and 9911.Ic which 9912builtins and numerous bug fixes, modifications 9913and speedups 9914. 9915.It Chris Kingsley, Caltech 9916Fast storage allocator routines 9917. 9918.It Chris Grevstad, TRW, 1987 9919Incorporated 4.3BSD 9920.Xr csh 1 9921into 9922.Nm 9923. 9924.It Christos S. Zoulas, Cornell U. EE Dept., 1987-94 9925Ports to HPUX, SVR2 and SVR3, a SysV version of getwd.c, SHORT_STRINGS support 9926and a new version of sh.glob.c 9927. 9928.It James J Dempsey, BBN, and Paul Placeway, OSU, 1988 9929A/UX port 9930. 9931.It Daniel Long, NNSC, 1988 9932.Ic wordchars 9933. 9934.It Patrick Wolfe, Kuck and Associates, Inc., 1988 9935.Ic vi 9936mode cleanup 9937. 9938.It David C Lawrence, Rensselaer Polytechnic Institute, 1989 9939.Ic autolist 9940and ambiguous completion listing 9941. 9942.It Alec Wolman, DEC, 1989 9943Newlines in the prompt 9944. 9945.It Matt Landau, BBN, 1989 9946.Pa ~/.tcshrc 9947. 9948.It Ray Moody, Purdue Physics, 1989 9949Magic space bar history expansion 9950. 9951.It Mordechai ????, Intel, 1989 9952printprompt() fixes and additions 9953. 9954.It Kazuhiro Honda, Dept. of Computer Science, Keio University, 1989 9955Automatic spelling correction and 9956.Ic prompt3 9957. 9958.It Per Hedeland, Ellemtel, Sweden, 1990- 9959Various bugfixes, improvements and manual updates 9960. 9961.It Hans J. Albertsson (Sun Sweden) 9962.Ic ampm , 9963.Ic settc , 9964and 9965.Ic telltc 9966. 9967.It Michael Bloom 9968Interrupt handling fixes 9969. 9970.It Michael Fine, Digital Equipment Corp 9971Extended key support 9972. 9973.It Eric Schnoebelen, Convex, 1990 9974Convex support, lots of 9975.Xr csh 1 9976bug fixes, 9977save and restore of directory stack 9978. 9979.It Ron Flax, Apple, 1990 9980A/UX 2.0 (re)port 9981. 9982.It Dan Oscarsson, LTH Sweden, 1990 9983NLS support and simulated NLS support for non NLS sites, fixes 9984. 9985.It Johan Widen, SICS Sweden, 1990 9986.Ic shlvl , 9987Mach support, 9988.Ic correct-line , 99898-bit printing 9990. 9991.It Matt Day, Sanyo Icon, 1990 9992POSIX termio support, SysV limit fixes 9993. 9994.It Jaap Vermeulen, Sequent, 1990-91 9995Vi mode fixes, expand-line, window change fixes, Symmetry port 9996. 9997.It Martin Boyer, Institut de recherche d'Hydro-Quebec, 1991 9998.Ic autolist 9999beeping options, modified the history search to search for 10000the whole string from the beginning of the line to the cursor. 10001. 10002.It Scott Krotz, Motorola, 1991 10003Minix port 10004. 10005.It David Dawes, Sydney U. Australia, Physics Dept., 1991 10006SVR4 job control fixes 10007. 10008.It Jose Sousa, Interactive Systems Corp., 1991 10009Extended 10010.Ic vi 10011fixes and 10012.Ic vi 10013delete command 10014. 10015.It Marc Horowitz, MIT, 1991 10016ANSIfication fixes, new exec hashing code, imake fixes, 10017.Ic where 10018. 10019.It Bruce Sterling Woodcock, sterling@netcom.com, 1991-1995 10020ETA and Pyramid port, Makefile and lint fixes, 10021.Ic ignoreeof Ns 10022=n addition, and 10023various other portability changes and bug fixes 10024. 10025.It Jeff Fink, 1992 10026.Ic complete-word-fwd 10027and 10028.Ic complete-word-back 10029. 10030.It Harry C. Pulley, 1992 10031Coherent port 10032. 10033.It Andy Phillips, Mullard Space Science Lab U.K., 1992 10034VMS-POSIX port 10035. 10036.It Beto Appleton, IBM Corp., 1992 10037Walking process group fixes, 10038.Xr csh 1 10039bug fixes, 10040POSIX file tests, POSIX SIGHUP 10041. 10042.It Scott Bolte, Cray Computer Corp., 1992 10043CSOS port 10044. 10045.It Kaveh R. Ghazi, Rutgers University, 1992 10046Tek, m88k, Titan and Masscomp ports and fixes. 10047Added autoconf support. 10048. 10049.It Mark Linderman, Cornell University, 1992 10050OS/2 port 10051. 10052.It Mika Liljeberg, liljeber@kruuna.Helsinki.FI, 1992 10053Linux port 10054. 10055.It Tim P. Starrin, NASA Langley Research Center Operations, 1993 10056Read-only variables 10057. 10058.It Dave Schweisguth, Yale University, 1993-4 10059New man page and tcsh.man2html 10060. 10061.It Larry Schwimmer, Stanford University, 1993 10062AFS and HESIOD patches 10063. 10064.It Luke Mewburn, 1991- 10065Enhanced directory printing in prompt. 10066Added 10067.Ic ellipsis 10068and 10069.Ic rprompt . 10070.Ic vimode 10071improvements. 10072Manual page improvements. 10073. 10074.It Edward Hutchins, Silicon Graphics Inc., 1996 10075Added implicit cd. 10076. 10077.It Martin Kraemer, 1997 10078Ported to Siemens Nixdorf EBCDIC machine 10079. 10080.It Amol Deshpande, Microsoft, 1997 10081Ported to WIN32 (Windows/95 and Windows/NT); wrote all the missing library 10082and message catalog code to interface to Windows. 10083. 10084.It Taga Nayuta, 1998 10085Color ls additions. 10086. 10087.El 10088. 10089.Sh "THANKS TO" 10090Bryan Dunlap, Clayton Elwell, Karl Kleinpaste, Bob Manson, Steve Romig, 10091Diana Smetters, Bob Sutterfield, Mark Verber, Elizabeth Zwicky and all 10092the other people at Ohio State for suggestions and encouragement 10093.Pp 10094All the people on the net, for putting up with, 10095reporting bugs in, and suggesting new additions to each and every version 10096.Pp 10097Richard M. Alderson III, for writing the 10098.Sq T in tcsh 10099section 10100