1.\" Copyright (c) 1980, 1990, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)csh.1 8.2 (Berkeley) 01/21/94 7.\" 8.Dd 9.Dt CSH 1 10.Os BSD 4 11.Sh NAME 12.Nm csh 13.Nd a shell (command interpreter) with C-like syntax 14.Sh SYNOPSIS 15.Nm csh 16.Op Fl bcefinstvVxX 17.Op arg ... 18.Nm csh 19.Op Fl l 20.Sh DESCRIPTION 21The 22.Nm csh 23is a command language interpreter 24incorporating a history mechanism (see 25.Nm History Substitutions ) , 26job control facilities (see 27.Nm Jobs ) , 28interactive file name 29and user name completion (see 30.Nm File Name Completion ) , 31and a C-like syntax. It is used both as an interactive 32login shell and a shell script command processor. 33.Ss Argument list processing 34If the first argument (argument 0) to the shell is 35.Ql Fl \& , 36then this is a login shell. 37A login shell also can be specified by invoking the shell with the 38.Ql Fl l 39flag as the only argument. 40.Pp 41The rest of the flag arguments are interpreted as follows: 42.Bl -tag -width 5n 43.It Fl b 44This flag forces a ``break'' from option processing, causing any further 45shell arguments to be treated as non-option arguments. 46The remaining arguments will not be interpreted as shell options. 47This may be used to pass options to a shell script without confusion 48or possible subterfuge. 49The shell will not run a set-user ID script without this option. 50.It Fl c 51Commands are read from the (single) following argument which must 52be present. 53Any remaining arguments are placed in 54.Ar argv . 55.It Fl e 56The shell exits if any invoked command terminates abnormally 57or yields a non-zero exit status. 58.It Fl f 59The shell will start faster, because it will neither search for nor 60execute commands from the file 61.Pa \&.cshrc 62in the invoker's home directory. 63.It Fl i 64The shell is interactive and prompts for its top-level input, 65even if it appears not to be a terminal. 66Shells are interactive without this option if their inputs 67and outputs are terminals. 68.It Fl l 69The shell is a login shell (only applicable if 70.Fl l 71is the only flag specified). 72.It Fl n 73Commands are parsed, but not executed. 74This aids in syntactic checking of shell scripts. 75.It Fl s 76Command input is taken from the standard input. 77.It Fl t 78A single line of input is read and executed. 79A 80.Ql \e 81may be used to escape the newline at the end of this 82line and continue onto another line. 83.It Fl v 84Causes the 85.Ar verbose 86variable to be set, with the effect 87that command input is echoed after history substitution. 88.It Fl x 89Causes the 90.Ar echo 91variable to be set, so that commands are echoed immediately before execution. 92.It Fl V 93Causes the 94.Ar verbose 95variable to be set even before 96.Pa .cshrc 97is executed. 98.It Fl X 99Is to 100.Fl x 101as 102.Fl V 103is to 104.Fl v . 105.El 106.Pp 107After processing of flag arguments, if arguments remain but none of the 108.Fl c , 109.Fl i , 110.Fl s , 111or 112.Fl t 113options were given, the first argument is taken as the name of a file of 114commands to be executed. 115The shell opens this file, and saves its name for possible resubstitution 116by `$0'. 117Since many systems use either the standard version 6 or version 7 shells 118whose shell scripts are not compatible with this shell, the shell will 119execute such a `standard' shell if the first character of a script 120is not a `#', i.e., if the script does not start with a comment. 121Remaining arguments initialize the variable 122.Ar argv . 123.Pp 124An instance of 125.Nm csh 126begins by executing commands from the file 127.Pa /etc/csh.cshrc 128and, 129if this is a login shell, 130.Pa \&/etc/csh.login . 131It then executes 132commands from 133.Pa \&.cshrc 134in the 135.Ar home 136directory of the invoker, and, if this is a login shell, the file 137.Pa \&.login 138in the same location. 139It is typical for users on crt's to put the command ``stty crt'' 140in their 141.Pa \&.login 142file, and to also invoke 143.Xr tset 1 144there. 145.Pp 146In the normal case, the shell will begin reading commands from the 147terminal, prompting with `% '. 148Processing of arguments and the use of the shell to process files 149containing command scripts will be described later. 150.Pp 151The shell repeatedly performs the following actions: 152a line of command input is read and broken into 153.Ar words . 154This sequence of words is placed on the command history list and parsed. 155Finally each command in the current line is executed. 156.Pp 157When a login shell terminates it executes commands from the files 158.Pa .logout 159in the user's 160.Ar home 161directory and 162.Pa /etc/csh.logout . 163.Ss Lexical structure 164The shell splits input lines into words at blanks and tabs with the 165following exceptions. 166The characters 167`&' `\&|' `;' `<' `>' `(' `)' 168form separate words. 169If doubled in `&&', `\&|\&|', `<<' or `>>' these pairs form single words. 170These parser metacharacters may be made part of other words, or prevented their 171special meaning, by preceding them with `\e'. 172A newline preceded by a `\e' is equivalent to a blank. 173.Pp 174Strings enclosed in matched pairs of quotations, 175`'\|', `\*(ga' or `"', 176form parts of a word; metacharacters in these strings, including blanks 177and tabs, do not form separate words. 178These quotations have semantics to be described later. 179Within pairs of `\'' or `"' characters, a newline preceded by a `\e' gives 180a true newline character. 181.Pp 182When the shell's input is not a terminal, 183the character `#' introduces a comment that continues to the end of the 184input line. 185It is prevented this special meaning when preceded by `\e' 186and in quotations using `\`', `\'', and `"'. 187.Ss Commands 188A simple command is a sequence of words, the first of which 189specifies the command to be executed. 190A simple command or 191a sequence of simple commands separated by `\&|' characters 192forms a pipeline. 193The output of each command in a pipeline is connected to the input of the next. 194Sequences of pipelines may be separated by `;', and are then executed 195sequentially. 196A sequence of pipelines may be executed without immediately 197waiting for it to terminate by following it with an `&'. 198.Pp 199Any of the above may be placed in `(' `)' to form a simple command (that 200may be a component of a pipeline, etc.). 201It is also possible to separate pipelines with `\&|\&|' or `&&' showing, 202as in the C language, 203that the second is to be executed only if the first fails or succeeds 204respectively. (See 205.Em Expressions . ) 206.Ss Jobs 207The shell associates a 208.Ar job 209with each pipeline. It keeps 210a table of current jobs, printed by the 211.Ar jobs 212command, and assigns them small integer numbers. When 213a job is started asynchronously with `&', the shell prints a line that looks 214like: 215.Bd -filled -offset indent 216.Op 1 2171234 218.Ed 219.Pp 220showing that the job which was started asynchronously was job number 2211 and had one (top-level) process, whose process id was 1234. 222.Pp 223If you are running a job and wish to do something else you may hit the key 224.Nm ^Z 225(control-Z) which sends a STOP signal to the current job. 226The shell will then normally show that the job has been `Stopped', 227and print another prompt. You can then manipulate the state of this job, 228putting it in the 229.Em background 230with the 231.Ar bg 232command, or run some other 233commands and eventually bring the job back into the foreground with 234the 235.Em foreground 236command 237.Ar fg . 238A 239.Nm ^Z 240takes effect immediately and 241is like an interrupt in that pending output and unread input are discarded 242when it is typed. There is another special key 243.Nm ^Y 244that does not generate a STOP signal until a program attempts to 245.Xr read 2 246it. 247This request can usefully be typed ahead when you have prepared some commands 248for a job that you wish to stop after it has read them. 249.Pp 250A job being run in the background will stop if it tries to read 251from the terminal. Background jobs are normally allowed to produce output, 252but this can be disabled by giving the command ``stty tostop''. 253If you set this 254tty option, then background jobs will stop when they try to produce 255output like they do when they try to read input. 256.Pp 257There are several ways to refer to jobs in the shell. The character 258`%' introduces a job name. If you wish to refer to job number 1, you can 259name it as `%1'. Just naming a job brings it to the foreground; thus 260`%1' is a synonym for `fg %1', bringing job number 1 back into the foreground. 261Similarly saying `%1 &' resumes job number 1 in the background. 262Jobs can also be named by prefixes of the string typed in to start them, 263if these prefixes are unambiguous, thus `%ex' would normally restart 264a suspended 265.Xr ex 1 266job, if there were only one suspended job whose name began with 267the string `ex'. It is also possible to say `%?string' 268which specifies a job whose text contains 269.Ar string , 270if there is only one such job. 271.Pp 272The shell maintains a notion of the current and previous jobs. 273In output about jobs, the current job is marked with a `+' 274and the previous job with a `\-'. The abbreviation `%+' refers 275to the current job and `%\-' refers to the previous job. For close 276analogy with the syntax of the 277.Ar history 278mechanism (described below), 279`%%' is also a synonym for the current job. 280.Pp 281The job control mechanism requires that the 282.Xr stty 1 283option 284.Ic new 285be set. It is an artifact from a 286.Em new 287implementation 288of the 289tty driver that allows generation of interrupt characters from 290the keyboard to tell jobs to stop. See stty(1) for details 291on setting options in the new tty driver. 292.Ss Status reporting 293This shell learns immediately whenever a process changes state. 294It normally informs you whenever a job becomes blocked so that 295no further progress is possible, but only just before it prints 296a prompt. This is done so that it does not otherwise disturb your work. 297If, however, you set the shell variable 298.Ar notify , 299the shell will notify you immediately of changes of status in background 300jobs. 301There is also a shell command 302.Ar notify 303that marks a single process so that its status changes will be immediately 304reported. By default 305.Ar notify 306marks the current process; 307simply say `notify' after starting a background job to mark it. 308.Pp 309When you try to leave the shell while jobs are stopped, you will 310be warned that `You have stopped jobs.' You may use the 311.Ar jobs 312command to see what they are. If you do this or immediately try to 313exit again, the shell will not warn you a second time, and the suspended 314jobs will be terminated. 315.Ss File Name Completion 316When the file name completion feature is enabled by setting 317the shell variable 318.Ar filec 319(see 320.Ic set ) , 321.Nm csh 322will 323interactively complete file names and user names from unique 324prefixes, when they are input from the terminal followed by 325the escape character (the escape key, or control-[) 326For example, 327if the current directory looks like 328.Bd -literal -offset indent 329DSC.OLD bin cmd lib xmpl.c 330DSC.NEW chaosnet cmtest mail xmpl.o 331bench class dev mbox xmpl.out 332.Ed 333.Pp 334and the input is 335.Pp 336.Dl % vi ch<escape> 337.Pp 338.Nm csh 339will complete the prefix ``ch'' 340to the only matching file name ``chaosnet'', changing the input 341line to 342.Pp 343.Dl % vi chaosnet 344.Pp 345However, given 346.Pp 347.Dl % vi D<escape> 348.Pp 349.Nm csh 350will only expand the input to 351.Pp 352.Dl % vi DSC. 353.Pp 354and will sound the terminal bell to indicate that the expansion is 355incomplete, since there are two file names matching the prefix ``D''. 356.Pp 357If a partial file name is followed by the end-of-file character 358(usually control-D), then, instead of completing the name, 359.Nm csh 360will list all file names matching the prefix. For example, 361the input 362.Pp 363.Dl % vi D<control-D> 364.Pp 365causes all files beginning with ``D'' to be listed: 366.Pp 367.Dl DSC.NEW DSC.OLD 368.Pp 369while the input line remains unchanged. 370.Pp 371The same system of escape and end-of-file can also be used to 372expand partial user names, if the word to be completed 373(or listed) begins with the character ``~''. For example, 374typing 375.Pp 376.Dl cd ~ro<escape> 377.Pp 378may produce the expansion 379.Pp 380.Dl cd ~root 381.Pp 382The use of the terminal bell to signal errors or multiple matches 383can be inhibited by setting the variable 384.Ar nobeep . 385.Pp 386Normally, all files in the particular directory are candidates 387for name completion. Files with certain suffixes can be excluded 388from consideration by setting the variable 389.Ar fignore 390to the 391list of suffixes to be ignored. Thus, if 392.Ar fignore 393is set by 394the command 395.Pp 396.Dl % set fignore = (.o .out) 397.Pp 398then typing 399.Pp 400.Dl % vi x<escape> 401.Pp 402would result in the completion to 403.Pp 404.Dl % vi xmpl.c 405.Pp 406ignoring the files "xmpl.o" and "xmpl.out". 407However, if the only completion possible requires not ignoring these 408suffixes, then they are not ignored. In addition, 409.Ar fignore 410does not affect the listing of file names by control-D. All files 411are listed regardless of their suffixes. 412.Ss Substitutions 413We now describe the various transformations the shell performs on the 414input in the order in which they occur. 415.Ss History substitutions 416History substitutions place words from previous command input as portions 417of new commands, making it easy to repeat commands, repeat arguments 418of a previous command in the current command, or fix spelling mistakes 419in the previous command with little typing and a high degree of confidence. 420History substitutions begin with the character `!' and may begin 421.Ar anywhere 422in the input stream (with the proviso that they 423.Nm "do not" 424nest.) 425This `!' may be preceded by a `\e' to prevent its special meaning; for 426convenience, an `!' is passed unchanged when it is followed by a blank, 427tab, newline, `=' or `('. 428(History substitutions also occur when an input line begins with `\*(ua'. 429This special abbreviation will be described later.) 430Any input line that contains history substitution is echoed on the terminal 431before it is executed as it could have been typed without history substitution. 432.Pp 433Commands input from the terminal that consist of one or more words 434are saved on the history list. 435The history substitutions reintroduce sequences of words from these 436saved commands into the input stream. 437The size of the history list is controlled by the 438.Ar history 439variable; the previous command is always retained, 440regardless of the value of the history variable. 441Commands are numbered sequentially from 1. 442.Pp 443For definiteness, consider the following output from the 444.Ar history 445command: 446.Bd -literal -offset indent 447\09 write michael 44810 ex write.c 44911 cat oldwrite.c 45012 diff *write.c 451.Ed 452.Pp 453The commands are shown with their event numbers. 454It is not usually necessary to use event numbers, but the current event 455number can be made part of the 456.Ar prompt 457by placing an `!' in the prompt string. 458.Pp 459With the current event 13 we can refer to previous events by event 460number `!11', relatively as in `!\-2' (referring to the same event), 461by a prefix of a command word 462as in `!d' for event 12 or `!wri' for event 9, or by a string contained in 463a word in the command as in `!?mic?' also referring to event 9. 464These forms, without further change, simply reintroduce the words 465of the specified events, each separated by a single blank. 466As a special case, `!!' refers to the previous command; thus `!!' 467alone is a 468.Ar redo . 469.Pp 470To select words from an event we can follow the event specification by 471a `:' and a designator for the desired words. 472The words of an input line are numbered from 0, 473the first (usually command) word being 0, the second word (first argument) 474being 1, etc. 475The basic word designators are: 476.Pp 477.Bl -tag -width Ds -compact -offset indent 478.It \&0 479first (command) word 480.It Ar n 481.Ar n Ns 'th 482argument 483.It \*(ua 484first argument, i.e., `1' 485.It $ 486last argument 487.It % 488word matched by (immediately preceding) 489.No \&? Ns Ar s Ns \&? 490search 491.It Ar \&x\-y 492range of words 493.It Ar \&\-y 494abbreviates 495.Ar `\&0\-y\' 496.It * 497abbreviates `\*(ua\-$', or nothing if only 1 word in event 498.It Ar x* 499abbreviates 500.Ar `x\-$\' 501.It Ar x\- 502like 503.Ar `x*\' 504but omitting word `$' 505.El 506.Pp 507The `:' separating the event specification from the word designator 508can be omitted if the argument selector begins with a `\*(ua', `$', `*' 509`\-' or `%'. 510After the optional word designator can be 511placed a sequence of modifiers, each preceded by a `:'. 512The following modifiers are defined: 513.Pp 514.Bl -tag -width Ds -compact -offset indent 515.It h 516Remove a trailing pathname component, leaving the head. 517.It r 518Remove a trailing `.xxx' component, leaving the root name. 519.It e 520Remove all but the extension `.xxx' part. 521.It s Ns Ar /l/r/ 522Substitute 523.Ar l 524for 525.Ar r 526.It t 527Remove all leading pathname components, leaving the tail. 528.It \&& 529Repeat the previous substitution. 530.It g 531Apply the change once on each word, prefixing the above, e.g., `g&'. 532.It a 533Apply the change as many times as possible on a single word, prefixing 534the above. It can be used together with `g' to apply a substitution 535globally. 536.It p 537Print the new command line but do not execute it. 538.It q 539Quote the substituted words, preventing further substitutions. 540.It x 541Like q, but break into words at blanks, tabs and newlines. 542.El 543.Pp 544Unless preceded by a `g' the change is applied only to the first 545modifiable word. With substitutions, it is an error for no word to be 546applicable. 547.Pp 548The left hand side of substitutions are not regular expressions in the sense 549of the editors, but instead strings. 550Any character may be used as the delimiter in place of `/'; 551a `\e' quotes the delimiter into the 552.Ar l " " 553and 554.Ar r " " 555strings. 556The character `&' in the right hand side is replaced by the text from 557the left. 558A `\e' also quotes `&'. 559A null 560.Ar l 561(`//') 562uses the previous string either from an 563.Ar l 564or from a 565contextual scan string 566.Ar s 567in 568.No \&`!? Ns Ar s Ns \e?' . 569The trailing delimiter in the substitution may be omitted if a newline 570follows immediately as may the trailing `?' in a contextual scan. 571.Pp 572A history reference may be given without an event specification, e.g., `!$'. 573Here, the reference is to the previous command unless a previous 574history reference occurred on the same line in which case this form repeats 575the previous reference. 576Thus `!?foo?\*(ua !$' gives the first and last arguments 577from the command matching `?foo?'. 578.Pp 579A special abbreviation of a history reference occurs when the first 580non-blank character of an input line is a `\*(ua'. 581This is equivalent to `!:s\*(ua' providing a convenient shorthand for substitutions 582on the text of the previous line. 583Thus `\*(ualb\*(ualib' fixes the spelling of 584`lib' 585in the previous command. 586Finally, a history substitution may be surrounded with `{' and `}' 587if necessary to insulate it from the characters that follow. 588Thus, after `ls \-ld ~paul' we might do `!{l}a' to do `ls \-ld ~paula', 589while `!la' would look for a command starting with `la'. 590.Pp 591.Ss Quotations with \' and \&" 592The quotation of strings by `\'' and `"' can be used 593to prevent all or some of the remaining substitutions. 594Strings enclosed in `\'' are prevented any further interpretation. 595Strings enclosed in `"' may be expanded as described below. 596.Pp 597In both cases the resulting text becomes (all or part of) a single word; 598only in one special case (see 599.Em Command Substitution 600below) does a `"' quoted string yield parts of more than one word; 601`\'' quoted strings never do. 602.Ss Alias substitution 603The shell maintains a list of aliases that can be established, displayed 604and modified by the 605.Ar alias 606and 607.Ar unalias 608commands. 609After a command line is scanned, it is parsed into distinct commands and 610the first word of each command, left-to-right, is checked to see if it 611has an alias. 612If it does, then the text that is the alias for that command is reread 613with the history mechanism available 614as though that command were the previous input line. 615The resulting words replace the 616command and argument list. 617If no reference is made to the history list, then the argument list is 618left unchanged. 619.Pp 620Thus if the alias for `ls' is `ls \-l' the command `ls /usr' would map to 621`ls \-l /usr', the argument list here being undisturbed. 622Similarly if the alias for `lookup' was `grep !\*(ua /etc/passwd' then 623`lookup bill' would map to `grep bill /etc/passwd'. 624.Pp 625If an alias is found, the word transformation of the input text 626is performed and the aliasing process begins again on the reformed input line. 627Looping is prevented if the first word of the new text is the same as the old 628by flagging it to prevent further aliasing. 629Other loops are detected and cause an error. 630.Pp 631Note that the mechanism allows aliases to introduce parser metasyntax. 632Thus, we can `alias print \'pr \e!* \&| lpr\'' to make a command that 633.Ar pr Ns 's 634its arguments to the line printer. 635.Ss Variable substitution 636The shell maintains a set of variables, each of which has as value a list 637of zero or more words. 638Some of these variables are set by the shell or referred to by it. 639For instance, the 640.Ar argv 641variable is an image of the shell's argument list, and words of this 642variable's value are referred to in special ways. 643.Pp 644The values of variables may be displayed and changed by using the 645.Ar set 646and 647.Ar unset 648commands. 649Of the variables referred to by the shell a number are toggles; 650the shell does not care what their value is, 651only whether they are set or not. 652For instance, the 653.Ar verbose 654variable is a toggle that causes command input to be echoed. 655The setting of this variable results from the 656.Fl v 657command line option. 658.Pp 659Other operations treat variables numerically. 660The `@' command permits numeric calculations to be performed and the result 661assigned to a variable. 662Variable values are, however, always represented as (zero or more) strings. 663For the purposes of numeric operations, the null string is considered to be 664zero, and the second and additional words of multiword values are ignored. 665.Pp 666After the input line is aliased and parsed, and before each command 667is executed, variable substitution 668is performed keyed by `$' characters. 669This expansion can be prevented by preceding the `$' with a `\e' except 670within `"'s where it 671.Em always 672occurs, and within `\''s where it 673.Em never 674occurs. 675Strings quoted by `\*(ga' are interpreted later (see 676.Nm "Command substitution" 677below) so `$' substitution does not occur there until later, if at all. 678A `$' is passed unchanged if followed by a blank, tab, or end-of-line. 679.Pp 680Input/output redirections are recognized before variable expansion, 681and are variable expanded separately. 682Otherwise, the command name and entire argument list are expanded together. 683It is thus possible for the first (command) word (to this point) to generate 684more than one word, the first of which becomes the command name, 685and the rest of which become arguments. 686.Pp 687Unless enclosed in `"' or given the `:q' modifier the results of variable 688substitution may eventually be command and filename substituted. 689Within `"', a variable whose value consists of multiple words expands to a 690(portion of) a single word, with the words of the variables value 691separated by blanks. 692When the `:q' modifier is applied to a substitution 693the variable will expand to multiple words with each word separated 694by a blank and quoted to prevent later command or filename substitution. 695.Pp 696The following metasequences are provided for introducing variable values into 697the shell input. 698Except as noted, it is an error to reference a variable that is not set. 699.Pp 700.Bl -tag -width Ds -compact -offset indent 701.It $name 702.It ${name} 703Are replaced by the words of the value of variable 704.Ar name , 705each separated by a blank. 706Braces insulate 707.Ar name 708from following characters that would otherwise be part of it. 709Shell variables have names consisting of up to 20 letters and digits 710starting with a letter. The underscore character is considered a letter. 711If 712.Ar name 713is not a shell variable, but is set in the environment, then 714that value is returned (but 715.Nm : 716modifiers and the other forms 717given below are not available here). 718.It $name Ns Op selector 719.It ${name Ns [ selector ] } 720May be used to select only some of the words from the value of 721.Ar name . 722The selector is subjected to `$' substitution and may consist of a single 723number or two numbers separated by a `\-'. 724The first word of a variables value is numbered `1'. 725If the first number of a range is omitted it defaults to `1'. 726If the last number of a range is omitted it defaults to `$#name'. 727The selector `*' selects all words. 728It is not an error for a range to be empty if the second argument is omitted 729or in range. 730.It $#name 731.It ${#name} 732Gives the number of words in the variable. 733This is useful for later use in a 734`$argv[selector]'. 735.It $0 736Substitutes the name of the file from which command input is being read. 737An error occurs if the name is not known. 738.It $number 739.It ${number} 740Equivalent to 741`$argv[number]'. 742.It $* 743Equivalent to 744`$argv[*]'. 745The modifiers `:e', `:h', `:t', `:r', `:q' and `:x' may be applied to 746the substitutions above as may `:gh', `:gt' and `:gr'. 747If braces `{' '}' appear in the command form then the modifiers 748must appear within the braces. 749The current implementation allows only one `:' modifier on each `$' expansion. 750.El 751.Pp 752The following substitutions may not be modified with `:' modifiers. 753.Bl -tag -width Ds -compact -offset indent 754.It $?name 755.It ${?name} 756Substitutes the string `1' if name is set, `0' if it is not. 757.It $?0 758Substitutes `1' if the current input filename is known, `0' if it is not. 759.It \&$\&$\& 760Substitute the (decimal) process number of the (parent) shell. 761.It $! 762Substitute the (decimal) process number of the last background process 763started by this shell. 764.It $< 765Substitutes a line from the standard 766input, with no further interpretation. 767It can be used to read from the keyboard in a shell script. 768.El 769.Ss Command and filename substitution 770The remaining substitutions, command and filename substitution, 771are applied selectively to the arguments of builtin commands. 772By selectively, we mean that portions of expressions which are 773not evaluated are not subjected to these expansions. 774For commands that are not internal to the shell, the command 775name is substituted separately from the argument list. 776This occurs very late, 777after input-output redirection is performed, and in a child 778of the main shell. 779.Ss Command substitution 780Command substitution is shown by a command enclosed in `\*(ga'. 781The output from such a command is normally broken into separate words 782at blanks, tabs and newlines, with null words being discarded; 783this text then replaces the original string. 784Within `"'s, only newlines force new words; blanks and tabs are preserved. 785.Pp 786In any case, the single final newline does not force a new word. 787Note that it is thus possible for a command substitution to yield 788only part of a word, even if the command outputs a complete line. 789.Ss Filename substitution 790If a word contains any of the characters `*', `?', `[' or `{' 791or begins with the character `~', then that word is a candidate for 792filename substitution, also known as `globbing'. 793This word is then regarded as a pattern, and replaced with an alphabetically 794sorted list of file names that match the pattern. 795In a list of words specifying filename substitution it is an error for 796no pattern to match an existing file name, but it is not required 797for each pattern to match. 798Only the metacharacters `*', `?' and `[' imply pattern matching, 799the characters `~' and `{' being more akin to abbreviations. 800.Pp 801In matching filenames, the character `.' at the beginning of a filename 802or immediately following a `/', as well as the character `/' must 803be matched explicitly. 804The character `*' matches any string of characters, including the null 805string. 806The character `?' matches any single character. 807The sequence 808.Sq Op ... 809matches any one of the characters enclosed. 810Within 811.Sq Op ... , 812a pair of characters separated by `\-' matches any character lexically between 813the two (inclusive). 814.Pp 815The character `~' at the beginning of a filename refers to home 816directories. 817Standing alone, i.e., `~' it expands to the invokers home directory as reflected 818in the value of the variable 819.Ar home . 820When followed by a name consisting of letters, digits and `\-' characters, 821the shell searches for a user with that name and substitutes their 822home directory; thus `~ken' might expand to `/usr/ken' and `~ken/chmach' 823to `/usr/ken/chmach'. 824If the character `~' is followed by a character other than a letter or `/' 825or does not appear at the beginning of a word, 826it is left undisturbed. 827.Pp 828The metanotation `a{b,c,d}e' is a shorthand for `abe ace ade'. 829Left to right order is preserved, with results of matches being sorted 830separately at a low level to preserve this order. 831This construct may be nested. 832Thus, `~source/s1/{oldls,ls}.c' expands to 833`/usr/source/s1/oldls.c /usr/source/s1/ls.c' 834without chance of error 835if the home directory for `source' is `/usr/source'. 836Similarly `../{memo,*box}' might expand to `../memo ../box ../mbox'. 837(Note that `memo' was not sorted with the results of the match to `*box'.) 838As a special case `{', `}' and `{}' are passed undisturbed. 839.Ss Input/output 840The standard input and the standard output of a command may be redirected 841with the following syntax: 842.Pp 843.Bl -tag -width Ds -compact -offset indent 844.It < name 845Open file 846.Ar name 847(which is first variable, command and filename expanded) as the standard 848input. 849.It << word 850Read the shell input up to a line that is identical to 851.Ar word . 852.Ar Word 853is not subjected to variable, filename or command substitution, 854and each input line is compared to 855.Ar word 856before any substitutions are done on the input line. 857Unless a quoting `\e', `"', `\*(aa' or `\*(ga' appears in 858.Ar word , 859variable and command substitution is performed on the intervening lines, 860allowing `\e' to quote `$', `\e' and `\*(ga'. 861Commands that are substituted have all blanks, tabs, and newlines 862preserved, except for the final newline which is dropped. 863The resultant text is placed in an anonymous temporary file that 864is given to the command as its standard input. 865.It > name 866.It >! name 867.It >& name 868.It >&! name 869The file 870.Ar name 871is used as the standard output. 872If the file does not exist then it is created; 873if the file exists, it is truncated; its previous contents are lost. 874.Pp 875If the variable 876.Ar noclobber 877is set, then the file must not exist or be a character special file (e.g., a 878terminal or `/dev/null') or an error results. 879This helps prevent accidental destruction of files. 880Here, the `!' forms can be used to suppress this check. 881.Pp 882The forms involving `&' route the standard error output into the specified 883file as well as the standard output. 884.Ar Name 885is expanded in the same way as `<' input filenames are. 886.It >> name 887.It >>& name 888.It >>! name 889.It >>&! name 890Uses file 891.Ar name 892as the standard output; 893like `>' but places output at the end of the file. 894If the variable 895.Ar noclobber 896is set, then it is an error for the file not to exist unless 897one of the `!' forms is given. 898Otherwise similar to `>'. 899.El 900.Pp 901A command receives the environment in which the shell was 902invoked as modified by the input-output parameters and 903the presence of the command in a pipeline. 904Thus, unlike some previous shells, commands run from a file of shell commands 905have no access to the text of the commands by default; 906instead they receive the original standard input of the shell. 907The `<<' mechanism should be used to present inline data. 908This permits shell command scripts to function as components of pipelines 909and allows the shell to block read its input. 910Note that the default standard input for a command run detached is 911.Ar not 912modified to be the empty file 913.Pa /dev/null ; 914instead the standard input 915remains as the original standard input of the shell. If this is a terminal 916and if the process attempts to read from the terminal, then the process 917will block and the user will be notified (see 918.Sx Jobs 919above). 920.Pp 921The standard error output may be directed through 922a pipe with the standard output. 923Simply use the form `\&|&' instead of just `\&|'. 924.Ss Expressions 925Several of the builtin commands (to be described later) 926take expressions, in which the operators are similar to those of C, with 927the same precedence. 928These expressions appear in the 929.Nm @, 930.Ar exit , 931.Ar if , 932and 933.Ar while 934commands. 935The following operators are available: 936.Bd -ragged -offset indent 937\&|\&| && \&| \*(ua & == != =~ !~ <= >= 938< > << >> + \- * / % ! ~ ( ) 939.Ed 940.Pp 941Here the precedence increases to the right, 942`==' `!=' `=~' and `!~', `<=' `>=' `<' and `>', `<<' and `>>', `+' and `\-', 943`*' `/' and `%' being, in groups, at the same level. 944The `==' `!=' `=~' and `!~' operators compare their arguments as strings; 945all others operate on numbers. 946The operators `=~' and `!~' are like `!=' and `==' except that the right 947hand side is a 948.Ar pattern 949(containing, e.g., `*'s, `?'s and instances of `[...]') 950against which the left hand operand is matched. This reduces the 951need for use of the 952.Ar switch 953statement in shell scripts when all that is really needed is pattern matching. 954.Pp 955Strings that begin with `0' are considered octal numbers. 956Null or missing arguments are considered `0'. 957The result of all expressions are strings, 958which represent decimal numbers. 959It is important to note that no two components of an expression can appear 960in the same word; except when adjacent to components of expressions that 961are syntactically significant to the parser (`&' `\&|' `<' `>' `(' `)'), 962they should be surrounded by spaces. 963.Pp 964Also available in expressions as primitive operands are command executions 965enclosed in `{' and `}' 966and file enquiries of the form 967.Fl l 968.Ar name 969where 970.Ic l 971is one of: 972.Bd -literal -offset indent 973r read access 974w write access 975x execute access 976e existence 977o ownership 978z zero size 979f plain file 980d directory 981.Ed 982.Pp 983The specified name is command and filename expanded and then tested 984to see if it has the specified relationship to the real user. 985If the file does not exist or is inaccessible then all enquiries return 986false, i.e., `0'. 987Command executions succeed, returning true, i.e., `1', 988if the command exits with status 0, otherwise they fail, returning 989false, i.e., `0'. 990If more detailed status information is required then the command 991should be executed outside an expression and the variable 992.Ar status 993examined. 994.Ss Control flow 995The shell contains several commands that can be used to regulate the 996flow of control in command files (shell scripts) and 997(in limited but useful ways) from terminal input. 998These commands all operate by forcing the shell to reread or skip in its 999input and, because of the implementation, restrict the placement of some 1000of the commands. 1001.Pp 1002The 1003.Ic foreach , 1004.Ic switch , 1005and 1006.Ic while 1007statements, as well as the 1008.Ic if\-then\-else 1009form of the 1010.Ic if 1011statement require that the major keywords appear in a single simple command 1012on an input line as shown below. 1013.Pp 1014If the shell's input is not seekable, 1015the shell buffers up input whenever a loop is being read 1016and performs seeks in this internal buffer to accomplish the rereading 1017implied by the loop. 1018(To the extent that this allows, backward goto's will succeed on 1019non-seekable inputs.) 1020.Ss Builtin commands 1021Builtin commands are executed within the shell. 1022If a builtin command occurs as any component of a pipeline 1023except the last then it is executed in a subshell. 1024.Pp 1025.Bl -tag -width Ds -compact -offset indent 1026.It Ic alias 1027.It Ic alias Ar name 1028.It Ic alias Ar name wordlist 1029The first form prints all aliases. 1030The second form prints the alias for name. 1031The final form assigns the specified 1032.Ar wordlist 1033as the alias of 1034.Ar name ; 1035.Ar wordlist 1036is command and filename substituted. 1037.Ar Name 1038is not allowed to be 1039.Ar alias 1040or 1041.Ar unalias . 1042.Pp 1043.It Ic alloc 1044Shows the amount of dynamic memory acquired, broken down into used and 1045free memory. 1046With an argument shows the number of free and used blocks in each size 1047category. The categories start at size 8 and double at each step. 1048This command's output may vary across system types, since 1049systems other than the VAX may use a different memory allocator. 1050.Pp 1051.It Ic bg 1052.It Ic bg \&% Ns Ar job ... 1053Puts the current or specified jobs into the background, continuing them 1054if they were stopped. 1055.Pp 1056.It Ic break 1057Causes execution to resume after the 1058.Ic end 1059of the nearest enclosing 1060.Ic foreach 1061or 1062.Ic while . 1063The remaining commands on the current line are executed. 1064Multi-level breaks are thus possible by writing them all on one line. 1065.Pp 1066.It Ic breaksw 1067Causes a break from a 1068.Ic switch , 1069resuming after the 1070.Ic endsw . 1071.Pp 1072.It Ic case Ar label : 1073A label in a 1074.Ic switch 1075statement as discussed below. 1076.Pp 1077.It Ic cd 1078.It Ic cd Ar name 1079.It Ic chdir 1080.It Ic chdir Ar name 1081Change the shell's working directory to directory 1082.Ar name . 1083If no argument is given then change to the home directory of the user. 1084If 1085.Ar name 1086is not found as a subdirectory of the current directory (and does not begin 1087with `/', `./' or `../'), then each 1088component of the variable 1089.Ic cdpath 1090is checked to see if it has a subdirectory 1091.Ar name . 1092Finally, if all else fails but 1093.Ar name 1094is a shell variable whose value begins with `/', then this 1095is tried to see if it is a directory. 1096.Pp 1097.It Ic continue 1098Continue execution of the nearest enclosing 1099.Ic while 1100or 1101.Ic foreach . 1102The rest of the commands on the current line are executed. 1103.Pp 1104.It Ic default : 1105Labels the default case in a 1106.Ic switch 1107statement. 1108The default should come after all 1109.Ic case 1110labels. 1111.Pp 1112.It Ic dirs 1113Prints the directory stack; the top of the stack is at the left, 1114the first directory in the stack being the current directory. 1115.Pp 1116.It Ic echo Ar wordlist 1117.It Ic echo Fl n Ar wordlist 1118The specified words are written to the shell's standard output, separated 1119by spaces, and terminated with a newline unless the 1120.Fl n 1121option is specified. 1122.Pp 1123.It Ic else 1124.It Ic end 1125.It Ic endif 1126.It Ic endsw 1127See the description of the 1128.Ic foreach , 1129.Ic if , 1130.Ic switch , 1131and 1132.Ic while 1133statements below. 1134.Pp 1135.It Ic eval Ar arg ... 1136(As in 1137.Xr sh 1 . ) 1138The arguments are read as input to the shell and the resulting 1139command(s) executed in the context of the current shell. 1140This is usually used to execute commands 1141generated as the result of command or variable substitution, since 1142parsing occurs before these substitutions. See 1143.Xr tset 1 1144for an example of using 1145.Ic eval . 1146.Pp 1147.It Ic exec Ar command 1148The specified command is executed in place of the current shell. 1149.Pp 1150.It Ic exit 1151.It Ic exit Ar (expr ) 1152The shell exits either with the value of the 1153.Ic status 1154variable (first form) or with the value of the specified 1155.Ic expr 1156(second form). 1157.Pp 1158.It Ic fg 1159.It Ic fg % Ns Ar job ... 1160Brings the current or specified jobs into the foreground, continuing them if 1161they were stopped. 1162.Pp 1163.It Ic foreach Ar name (wordlist) 1164.It ... 1165.It Ic end 1166The variable 1167.Ic name 1168is successively set to each member of 1169.Ic wordlist 1170and the sequence of commands between this command and the matching 1171.Ic end 1172are executed. 1173(Both 1174.Ic foreach 1175and 1176.Ic end 1177must appear alone on separate lines.) 1178The builtin command 1179.Ic continue 1180may be used to continue the loop prematurely and the builtin 1181command 1182.Ic break 1183to terminate it prematurely. 1184When this command is read from the terminal, the loop is read once 1185prompting with `?' before any statements in the loop are executed. 1186If you make a mistake typing in a loop at the terminal you can rub it out. 1187.Pp 1188.It Ic glob Ar wordlist 1189Like 1190.Ic echo 1191but no `\e' escapes are recognized and words are delimited 1192by null characters in the output. 1193Useful for programs that wish to use the shell to filename expand a list 1194of words. 1195.Pp 1196.It Ic goto Ar word 1197The specified 1198.Ic word 1199is filename and command expanded to yield a string of the form `label'. 1200The shell rewinds its input as much as possible 1201and searches for a line of the form `label:' 1202possibly preceded by blanks or tabs. 1203Execution continues after the specified line. 1204.Pp 1205.It Ic hashstat 1206Print a statistics line showing how effective the internal hash 1207table has been at locating commands (and avoiding 1208.Ic exec Ns \'s ) . 1209An 1210.Ic exec 1211is attempted for each component of the 1212.Em path 1213where the hash function indicates a possible hit, and in each component 1214that does not begin with a `/'. 1215.Pp 1216.It Ic history 1217.It Ic history Ar n 1218.It Ic history Fl r Ar n 1219.It Ic history Fl h Ar n 1220Displays the history event list; if 1221.Ar n 1222is given only the 1223.Ar n 1224most recent events are printed. 1225The 1226.Fl r 1227option reverses the order of printout to be most recent first 1228instead of oldest first. 1229The 1230.Fl h 1231option causes the history list to be printed without leading numbers. 1232This format produces files suitable for sourcing using the \-h 1233option to 1234.Ic source . 1235.Pp 1236.It Ic if ( Ar expr ) No command 1237If the specified expression evaluates true, then the single 1238.Ar command 1239with arguments is executed. 1240Variable substitution on 1241.Ar command 1242happens early, at the same 1243time it does for the rest of the 1244.Ic if 1245command. 1246.Ar Command 1247must be a simple command, not 1248a pipeline, a command list, or a parenthesized command list. 1249Input/output redirection occurs even if 1250.Ar expr 1251is false, i.e., when command is 1252.Sy not 1253executed (this is a bug). 1254.Pp 1255.It Ic if ( Ar expr ) Ic then 1256.It ... 1257.It Ic else if ( Ar expr2 ) Ic then 1258.It ... 1259.It Ic else 1260.It ... 1261.It Ic endif 1262If the specified 1263.Ar expr 1264is true then the commands up to the first 1265.Ic else 1266are executed; otherwise if 1267.Ar expr2 1268is true then the commands up to the 1269second 1270.Ic else 1271are executed, etc. 1272Any number of 1273.Ic else-if 1274pairs are possible; only one 1275.Ic endif 1276is needed. 1277The 1278.Ic else 1279part is likewise optional. 1280(The words 1281.Ic else 1282and 1283.Ic endif 1284must appear at the beginning of input lines; 1285the 1286.Ic if 1287must appear alone on its input line or after an 1288.Ic else . ) 1289.Pp 1290.It Ic jobs 1291.It Ic jobs Fl l 1292Lists the active jobs; the 1293.Fl l 1294option lists process id's in addition to the normal information. 1295.Pp 1296.It Ic kill % Ns Ar job 1297.It Ic kill Ar pid 1298.It Ic kill Fl sig Ar pid ... 1299.It Ic kill Fl l 1300Sends either the TERM (terminate) signal or the 1301specified signal to the specified jobs or processes. 1302Signals are either given by number or by names (as given in 1303.Pa /usr/include/signal.h, 1304stripped of the prefix ``SIG''). 1305The signal names are listed by ``kill \-l''. 1306There is no default, just saying `kill' does not 1307send a signal to the current job. 1308If the signal being sent is TERM (terminate) or HUP (hangup), 1309then the job or process will be sent a CONT (continue) signal as well. 1310.Pp 1311.It Ic limit 1312.It Ic limit Ar resource 1313.It Ic limit Ar resource maximum-use 1314.It Ic limit Fl h 1315.It Ic limit Fl h Ar resource 1316.It Ic limit Fl h Ar resource maximum-use 1317Limits the consumption by the current process and each process 1318it creates to not individually exceed 1319.Ar maximum-use 1320on the 1321specified 1322.Ar resource . 1323If no 1324.Ar maximum-use 1325is given, then 1326the current limit is printed; if no 1327.Ar resource 1328is given, then 1329all limitations are given. If the 1330.Fl h 1331flag is given, the hard limits are used instead of the current 1332limits. The hard limits impose a ceiling on the values of 1333the current limits. Only the super-user may raise the hard limits, 1334but a user may lower or raise the current limits within the legal range. 1335.Pp 1336Resources controllable currently include 1337.Ar cputime 1338(the maximum 1339number of cpu-seconds to be used by each process), 1340.Ar filesize 1341(the largest single file that can be created), 1342.Ar datasize 1343(the maximum growth of the data+stack region via 1344.Xr sbrk 2 1345beyond the end of the program text), 1346.Ar stacksize 1347(the maximum 1348size of the automatically-extended stack region), and 1349.Ar coredumpsize 1350(the size of the largest core dump that will be created). 1351.Pp 1352The 1353.Ar maximum-use 1354may be given as a (floating point or integer) 1355number followed by a scale factor. For all limits other than 1356.Ar cputime 1357the default scale is `k' or `kilobytes' (1024 bytes); 1358a scale factor of `m' or `megabytes' may also be used. 1359For 1360.Ar cputime 1361the default scale is `seconds'; 1362a scale factor of `m' for minutes 1363or `h' for hours, or a time of the form `mm:ss' giving minutes 1364and seconds also may be used. 1365.Pp 1366For both 1367.Ar resource 1368names and scale factors, unambiguous prefixes 1369of the names suffice. 1370.Pp 1371.It Ic login 1372Terminate a login shell, replacing it with an instance of 1373.Pa /bin/login. 1374This is one way to log off, included for compatibility with 1375.Xr sh 1 . 1376.Pp 1377.It Ic logout 1378Terminate a login shell. 1379Especially useful if 1380.Ic ignoreeof 1381is set. 1382.Pp 1383.It Ic nice 1384.It Ic nice Ar +number 1385.It Ic nice Ar command 1386.It Ic nice Ar +number command 1387The first form sets the 1388scheduling priority 1389for this shell to 4. 1390The second form sets the 1391priority 1392to the given 1393.Ar number . 1394The final two forms run command at priority 4 and 1395.Ar number 1396respectively. 1397The greater the number, the less cpu the process will get. 1398The super-user may specify negative priority by using `nice \-number ...'. 1399.Ar Command 1400is always executed in a sub-shell, and the restrictions 1401placed on commands in simple 1402.Ic if 1403statements apply. 1404.Pp 1405.It Ic nohup 1406.It Ic nohup Ar command 1407The first form can be used in shell scripts to cause hangups to be 1408ignored for the remainder of the script. 1409The second form causes the specified command to be run with hangups 1410ignored. 1411All processes detached with `&' are effectively 1412.Ic nohup Ns \'ed . 1413.Pp 1414.It Ic notify 1415.It Ic notify % Ns Ar job ... 1416Causes the shell to notify the user asynchronously when the status of the 1417current or specified jobs change; normally notification is presented 1418before a prompt. This is automatic if the shell variable 1419.Ic notify 1420is set. 1421.Pp 1422.It Ic onintr 1423.It Ic onintr Fl 1424.It Ic onintr Ar label 1425Control the action of the shell on interrupts. 1426The first form restores the default action of the shell on interrupts 1427which is to terminate shell scripts or to return to the terminal command 1428input level. 1429The second form `onintr \-' causes all interrupts to be ignored. 1430The final form causes the shell to execute a `goto label' when 1431an interrupt is received or a child process terminates because 1432it was interrupted. 1433.Pp 1434In any case, if the shell is running detached and interrupts are 1435being ignored, all forms of 1436.Ic onintr 1437have no meaning and interrupts 1438continue to be ignored by the shell and all invoked commands. 1439Finally 1440.Ic onintr 1441statements are ignored in the system startup files where interrupts 1442are disabled (/etc/csh.cshrc, /etc/csh.login). 1443.Pp 1444.It Ic popd 1445.It Ic popd Ar +n 1446Pops the directory stack, returning to the new top directory. 1447With an argument 1448.Ns \`+ Ar n Ns \' 1449discards the 1450.Ar n Ns \'th 1451entry in the stack. 1452The members of the directory stack are numbered from the top starting at 0. 1453.Pp 1454.It Ic pushd 1455.It Ic pushd Ar name 1456.It Ic pushd Ar n 1457With no arguments, 1458.Ic pushd 1459exchanges the top two elements of the directory stack. 1460Given a 1461.Ar name 1462argument, 1463.Ic pushd 1464changes to the new directory (ala 1465.Ic cd ) 1466and pushes the old current working directory 1467(as in 1468.Ic csw ) 1469onto the directory stack. 1470With a numeric argument, 1471.Ic pushd 1472rotates the 1473.Ar n Ns \'th 1474argument of the directory 1475stack around to be the top element and changes to it. The members 1476of the directory stack are numbered from the top starting at 0. 1477.Pp 1478.It Ic rehash 1479Causes the internal hash table of the contents of the directories in 1480the 1481.Ic path 1482variable to be recomputed. This is needed if new commands are added 1483to directories in the 1484.Ic path 1485while you are logged in. This should only be necessary if you add 1486commands to one of your own directories, or if a systems programmer 1487changes the contents of a system directory. 1488.Pp 1489.It Ic repeat Ar count command 1490The specified 1491.Ar command 1492which is subject to the same restrictions 1493as the 1494.Ar command 1495in the one line 1496.Ic if 1497statement above, 1498is executed 1499.Ar count 1500times. 1501I/O redirections occur exactly once, even if 1502.Ar count 1503is 0. 1504.Pp 1505.It Ic set 1506.It Ic set Ar name 1507.It Ic set Ar name Ns =word 1508.It Ic set Ar name[index] Ns =word 1509.It Ic set Ar name Ns =(wordlist) 1510The first form of the command shows the value of all shell variables. 1511Variables that have other than a single word as their 1512value print as a parenthesized word list. 1513The second form sets 1514.Ar name 1515to the null string. 1516The third form sets 1517.Ar name 1518to the single 1519.Ar word . 1520The fourth form sets 1521the 1522.Ar index Ns 'th 1523component of 1524.Ar name 1525to 1526.Ar word ; 1527this component must already exist. 1528The final form sets 1529.Ar name 1530to the list of words in 1531.Ar wordlist . 1532The value is always command and filename expanded. 1533.Pp 1534These arguments may be repeated to set multiple values in a single set command. 1535Note however, that variable expansion happens for all arguments before any 1536setting occurs. 1537.Pp 1538.It Ic setenv 1539.It Ic setenv Ar name 1540.It Ic setenv Ar name value 1541The first form lists all current environment variables. 1542It is equivalent to 1543.Xr printenv 1 . 1544The last form sets the value of environment variable 1545.Ar name 1546to be 1547.Ar value , 1548a single string. The second form sets 1549.Ar name 1550to an empty string. 1551The most commonly used environment variables 1552.Ev USER , 1553.Ev TERM , 1554and 1555.Ev PATH 1556are automatically imported to and exported from the 1557.Nm csh 1558variables 1559.Ar user , 1560.Ar term , 1561and 1562.Ar path ; 1563there is no need to use 1564.Ic setenv 1565for these. 1566.Pp 1567.It Ic shift 1568.It Ic shift Ar variable 1569The members of 1570.Ic argv 1571are shifted to the left, discarding 1572.Ic argv Ns Bq 1 . 1573It is an error for 1574.Ic argv 1575not to be set or to have less than one word as value. 1576The second form performs the same function on the specified variable. 1577.Pp 1578.It Ic source Ar name 1579.It Ic source Fl h Ar name 1580The shell reads commands from 1581.Ar name . 1582.Ic Source 1583commands may be nested; if they are nested too deeply the shell may 1584run out of file descriptors. 1585An error in a 1586.Ic source 1587at any level terminates all nested 1588.Ic source 1589commands. 1590Normally input during 1591.Ic source 1592commands is not placed on the history list; 1593the \-h option causes the commands to be placed on the 1594history list without being executed. 1595.Pp 1596.It Ic stop 1597.It Ic stop % Ns Ar job ... 1598Stops the current or specified jobs that are executing in the background. 1599.Pp 1600.It Ic suspend 1601Causes the shell to stop in its tracks, much as if it had been sent a stop 1602signal with 1603.Ic ^Z . 1604This is most often used to stop shells started by 1605.Xr su 1 . 1606.Pp 1607.It Ic switch Ar (string) 1608.It Ic case Ar str1 : 1609.It \ \ \ \ \&... 1610.It Ic \ \ \ \ breaksw 1611.It \ \ \ \ \&... 1612.It Ic default : 1613.It \ \ \ \ \&... 1614.It Ic \ \ \ \ breaksw 1615.It Ic endsw 1616Each case label is successively matched against the specified 1617.Ar string 1618which is first command and filename expanded. 1619The file metacharacters `*', `?' and `[...]' 1620may be used in the case labels, 1621which are variable expanded. 1622If none of the labels match before the `default' label is found, then 1623the execution begins after the default label. 1624Each case label and the default label must appear at the beginning of a line. 1625The command 1626.Ic breaksw 1627causes execution to continue after the 1628.Ic endsw . 1629Otherwise control may fall through case labels and the default label as in C. 1630If no label matches and there is no default, execution continues after 1631the 1632.Ic endsw . 1633.Pp 1634.It Ic time 1635.It Ic time Ar command 1636With no argument, a summary of time used by this shell and its children 1637is printed. 1638If arguments are given 1639the specified simple command is timed and a time summary 1640as described under the 1641.Ic time 1642variable is printed. If necessary, an extra shell is created to print the time 1643statistic when the command completes. 1644.Pp 1645.It Ic umask 1646.It Ic umask Ar value 1647The file creation mask is displayed (first form) or set to the specified 1648value (second form). The mask is given in octal. Common values for 1649the mask are 002 giving all access to the group and read and execute 1650access to others or 022 giving all access except write access for 1651users in the group or others. 1652.Pp 1653.It Ic unalias Ar pattern 1654All aliases whose names match the specified pattern are discarded. 1655Thus all aliases are removed by `unalias *'. 1656It is not an error for nothing to be 1657.Ic unaliased . 1658.Pp 1659.It Ic unhash 1660Use of the internal hash table to speed location of executed programs 1661is disabled. 1662.Pp 1663.It Ic unlimit 1664.It Ic unlimit Ar resource 1665.It Ic unlimit Fl h 1666.It Ic unlimit Fl h Ar resource 1667Removes the limitation on 1668.Ar resource . 1669If no 1670.Ar resource 1671is specified, then all 1672.Ar resource 1673limitations are removed. If 1674.Fl h 1675is given, the corresponding hard limits are removed. Only the 1676super-user may do this. 1677.Pp 1678.It Ic unset Ar pattern 1679All variables whose names match the specified pattern are removed. 1680Thus all variables are removed by `unset *'; this has noticeably 1681distasteful side-effects. 1682It is not an error for nothing to be 1683.Ic unset . 1684.Pp 1685.It Ic unsetenv Ar pattern 1686Removes all variables whose name match the specified pattern from the 1687environment. See also the 1688.Ic setenv 1689command above and 1690.Xr printenv 1 . 1691.Pp 1692.It Ic wait 1693Wait for all background jobs. 1694If the shell is interactive, then an interrupt can disrupt the wait. 1695After the interrupt, the shell prints names and job numbers of all jobs 1696known to be outstanding. 1697.It Ic which Ar command 1698Displays the resolved command that will be executed by the shell. 1699.Pp 1700.It Ic while Ar (expr) 1701.It \&... 1702.It Ic end 1703While the specified expression evaluates non-zero, the commands between 1704the 1705.Ic while 1706and the matching 1707.Ic end 1708are evaluated. 1709.Ic Break 1710and 1711.Ic continue 1712may be used to terminate or continue the loop prematurely. 1713(The 1714.Ic while 1715and 1716.Ic end 1717must appear alone on their input lines.) 1718Prompting occurs here the first time through the loop as for the 1719.Ic foreach 1720statement if the input is a terminal. 1721.Pp 1722.It Ic % Ns Ar job 1723Brings the specified job into the foreground. 1724.Pp 1725.It Ic % Ns Ar job Ic & 1726Continues the specified job in the background. 1727.Pp 1728.It Ic @ 1729.It Ic @ Ns Ar name Ns = expr 1730.It Ic @ Ns Ar name[index] Ns = expr 1731The first form prints the values of all the shell variables. 1732The second form sets the specified 1733.Ar name 1734to the value of 1735.Ar expr . 1736If the expression contains `<', `>', `&' or `|' then at least 1737this part of the expression must be placed within `(' `)'. 1738The third form assigns the value of 1739.Ar expr 1740to the 1741.Ar index Ns 'th 1742argument of 1743.Ar name . 1744Both 1745.Ar name 1746and its 1747.Ar index Ns 'th 1748component must already exist. 1749.El 1750.Pp 1751The operators `*=', `+=', etc are available as in C. 1752The space separating the name from the assignment operator is optional. 1753Spaces are, however, mandatory in separating components of 1754.Ar expr 1755which would otherwise be single words. 1756.Pp 1757Special postfix `+\|+' and `\-\|\-' operators increment and decrement 1758.Ar name 1759respectively, i.e., `@ i++'. 1760.Ss Pre-defined and environment variables 1761The following variables have special meaning to the shell. 1762Of these, 1763.Ar argv , 1764.Ar cwd, 1765.Ar home , 1766.Ar path, 1767.Ar prompt , 1768.Ar shell 1769and 1770.Ar status 1771are always set by the shell. 1772Except for 1773.Ar cwd 1774and 1775.Ar status , 1776this setting occurs only at initialization; 1777these variables will not then be modified unless done 1778explicitly by the user. 1779.Pp 1780The shell copies the environment variable 1781.Ev USER 1782into the variable 1783.Ar user , 1784.Ev TERM 1785into 1786.Ar term , 1787and 1788.Ev HOME 1789into 1790.Ar home , 1791and copies these back into the environment whenever the normal 1792shell variables are reset. 1793The environment variable 1794.Ev PATH 1795is likewise handled; it is not 1796necessary to worry about its setting other than in the file 1797.Ar \&.cshrc 1798as inferior 1799.Nm csh 1800processes will import the definition of 1801.Ar path 1802from the environment, and re-export it if you then change it. 1803.Bl -tag -width histchars 1804.It Ic argv 1805Set to the arguments to the shell, it is from this variable that 1806positional parameters are substituted, i.e., `$1' is replaced by 1807`$argv[1]', 1808etc. 1809.It Ic cdpath 1810Gives a list of alternate directories searched to find subdirectories 1811in 1812.Ar chdir 1813commands. 1814.It Ic cwd 1815The full pathname of the current directory. 1816.It Ic echo 1817Set when the 1818.Fl x 1819command line option is given. 1820Causes each command and its arguments 1821to be echoed just before it is executed. 1822For non-builtin commands all expansions occur before echoing. 1823Builtin commands are echoed before command and filename substitution, 1824since these substitutions are then done selectively. 1825.It Ic filec 1826Enable file name completion. 1827.It Ic histchars 1828Can be given a string value to change the characters used in history 1829substitution. The first character of its value is used as the 1830history substitution character, replacing the default character `!'. 1831The second character of its value replaces the character `\(ua' in 1832quick substitutions. 1833.It Ic histfile 1834Can be set to the pathname where history is going to be saved/restored. 1835.It Ic history 1836Can be given a numeric value to control the size of the history list. 1837Any command that has been referenced in this many events will not be 1838discarded. 1839Too large values of 1840.Ar history 1841may run the shell out of memory. 1842The last executed command is always saved on the history list. 1843.It Ic home 1844The home directory of the invoker, initialized from the environment. 1845The filename expansion of 1846.Sq Pa ~ 1847refers to this variable. 1848.It Ic ignoreeof 1849If set the shell ignores 1850end-of-file from input devices which are terminals. 1851This prevents shells from accidentally being killed by control-D's. 1852.It Ic mail 1853The files where the shell checks for mail. 1854This checking is done after each command completion that will 1855result in a prompt, 1856if a specified interval has elapsed. 1857The shell says `You have new mail.' 1858if the file exists with an access time not greater than its modify time. 1859.Pp 1860If the first word of the value of 1861.Ar mail 1862is numeric it specifies a different mail checking interval, in seconds, 1863than the default, which is 10 minutes. 1864.Pp 1865If multiple mail files are specified, then the shell says 1866`New mail in 1867.Ar name Ns ' 1868when there is mail in the file 1869.Ar name . 1870.It Ic noclobber 1871As described in the section on 1872.Sx input/output , 1873restrictions are placed on output redirection to insure that 1874files are not accidentally destroyed, and that `>>' redirections 1875refer to existing files. 1876.It Ic noglob 1877If set, filename expansion is inhibited. 1878This inhibition is most useful in shell scripts that 1879 are not dealing with filenames, 1880or after a list of filenames has been obtained and further expansions 1881are not desirable. 1882.It Ic nonomatch 1883If set, it is not an error for a filename expansion to not match any 1884existing files; instead the primitive pattern is returned. 1885It is still an error for the primitive pattern to be malformed, i.e., 1886`echo [' 1887still gives an error. 1888.It Ic notify 1889If set, the shell notifies asynchronously of job completions; 1890the default is to present job completions just before printing 1891a prompt. 1892.It Ic path 1893Each word of the path variable specifies a directory in which 1894commands are to be sought for execution. 1895A null word specifies the current directory. 1896If there is no 1897.Ar path 1898variable then only full path names will execute. 1899The usual search path is `.', `/bin' and `/usr/bin', but this 1900may vary from system to system. 1901For the super-user the default search path is `/etc', `/bin' and `/usr/bin'. 1902A shell that is given neither the 1903.Fl c 1904nor the 1905.Fl t 1906option will normally hash the contents of the directories in the 1907.Ar path 1908variable after reading 1909.Ar \&.cshrc , 1910and each time the 1911.Ar path 1912variable is reset. If new commands are added to these directories 1913while the shell is active, it may be necessary to do a 1914.Ic rehash 1915or the commands may not be found. 1916.It Ic prompt 1917The string that is printed before each command is read from 1918an interactive terminal input. 1919If a `!' appears in the string it will be replaced by the current event number 1920unless a preceding `\e' is given. 1921Default is `% ', or `# ' for the super-user. 1922.It Ic savehist 1923Is given a numeric value to control the number of entries of the 1924history list that are saved in ~/.history when the user logs out. 1925Any command that has been referenced in this many events will be saved. 1926During start up the shell sources ~/.history into the history list 1927enabling history to be saved across logins. 1928Too large values of 1929.Ar savehist 1930will slow down the shell during start up. 1931If 1932.Ar savehist 1933is just set, the shell will use the value of 1934.Ar history. 1935.It Ic shell 1936The file in which the shell resides. 1937This variable is used in forking shells to interpret files that have execute 1938bits set, but which are not executable by the system. 1939(See the description of 1940.Sx Non-builtin Command Execution 1941below.) 1942Initialized to the (system-dependent) home of the shell. 1943.It Ic status 1944The status returned by the last command. 1945If it terminated abnormally, then 0200 is added to the status. 1946Builtin commands that fail return exit status `1', 1947all other builtin commands set status to `0'. 1948.It Ic time 1949Controls automatic timing of commands. 1950If set, then any command that takes more than this many cpu seconds 1951will cause a line giving user, system, and real times and a utilization 1952percentage which is the ratio of user plus system times to real time 1953to be printed when it terminates. 1954.It Ic verbose 1955Set by the 1956.Fl v 1957command line option, causes the words of each command to be printed 1958after history substitution. 1959.El 1960.Ss Non-builtin command execution 1961When a command to be executed is found to not be a builtin command 1962the shell attempts to execute the command via 1963.Xr execve 2 . 1964Each word in the variable 1965.Ar path 1966names a directory from which the shell will attempt to execute the command. 1967If it is given neither a 1968.Fl c 1969nor a 1970.Fl t 1971option, the shell will hash the names in these directories into an internal 1972table so that it will only try an 1973.Ic exec 1974in a directory if there is a possibility that the command resides there. 1975This shortcut greatly speeds command location when many directories 1976are present in the search path. 1977If this mechanism has been turned off (via 1978.Ic unhash ) , 1979or if the shell was given a 1980.Fl c 1981or 1982.Fl t 1983argument, and in any case for each directory component of 1984.Ar path 1985that does not begin with a `/', 1986the shell concatenates with the given command name to form a path name 1987of a file which it then attempts to execute. 1988.Pp 1989Parenthesized commands are always executed in a subshell. 1990Thus 1991.Pp 1992.Dl (cd ; pwd) ; pwd 1993.Pp 1994prints the 1995.Ar home 1996directory; leaving you where you were (printing this after the home directory), 1997while 1998.Pp 1999.Dl cd ; pwd 2000.Pp 2001leaves you in the 2002.Ar home 2003directory. 2004Parenthesized commands are most often used to prevent 2005.Ic chdir 2006from affecting the current shell. 2007.Pp 2008If the file has execute permissions but is not an 2009executable binary to the system, then it is assumed to be a 2010file containing shell commands and a new shell is spawned to read it. 2011.Pp 2012If there is an 2013.Ic alias 2014for 2015.Ic shell 2016then the words of the alias will be prepended to the argument list to form 2017the shell command. 2018The first word of the 2019.Ic alias 2020should be the full path name of the shell 2021(e.g., `$shell'). 2022Note that this is a special, late occurring, case of 2023.Ic alias 2024substitution, 2025and only allows words to be prepended to the argument list without change. 2026.Ss Signal handling 2027The shell normally ignores 2028.Ar quit 2029signals. 2030Jobs running detached (either by 2031.Ic \&& 2032or the 2033.Ic bg 2034or 2035.Ic %... & 2036commands) are immune to signals generated from the keyboard, including 2037hangups. 2038Other signals have the values which the shell inherited from its parent. 2039The shell's handling of interrupts and terminate signals 2040in shell scripts can be controlled by 2041.Ic onintr . 2042Login shells catch the 2043.Ar terminate 2044signal; otherwise this signal is passed on to children from the state in the 2045shell's parent. 2046Interrupts are not allowed when a login shell is reading the file 2047.Pa \&.logout . 2048.Sh AUTHOR 2049William Joy. 2050Job control and directory stack features first implemented by J.E. Kulp of 2051IIASA, Laxenburg, Austria, 2052with different syntax than that used now. 2053File name completion code written by Ken Greer, HP Labs. 2054Eight-bit implementation Christos S. Zoulas, Cornell University. 2055.Sh FILES 2056.Bl -tag -width /etc/passwd -compact 2057.It Pa ~/.cshrc 2058Read at beginning of execution by each shell. 2059.It Pa ~/.login 2060Read by login shell, after `.cshrc' at login. 2061.It Pa ~/.logout 2062Read by login shell, at logout. 2063.It Pa /bin/sh 2064Standard shell, for shell scripts not starting with a `#'. 2065.It Pa /tmp/sh* 2066Temporary file for `<<'. 2067.It Pa /etc/passwd 2068Source of home directories for `~name'. 2069.El 2070.Sh LIMITATIONS 2071Word lengths \- 2072Words can be no longer than 1024 characters. 2073The system limits argument lists to 10240 characters. 2074The number of arguments to a command that involves filename expansion 2075is limited to 1/6'th the number of characters allowed in an argument list. 2076Command substitutions may substitute no more characters than are 2077allowed in an argument list. 2078To detect looping, the shell restricts the number of 2079.Ic alias 2080substitutions on a single line to 20. 2081.Sh SEE ALSO 2082.Xr sh 1 , 2083.Xr access 2 , 2084.Xr execve 2 , 2085.Xr fork 2 , 2086.Xr killpg 2 , 2087.Xr pipe 2 , 2088.Xr sigvec 2 , 2089.Xr umask 2 , 2090.Xr setrlimit 2 , 2091.Xr wait 2 , 2092.Xr tty 4 , 2093.Xr a.out 5 , 2094.Xr environ 7 , 2095.br 2096.Em An introduction to the C shell 2097.Sh HISTORY 2098.Nm Csh 2099appeared in 2100.Bx 3 . 2101It 2102was a first implementation of a command language interpreter 2103incorporating a history mechanism (see 2104.Sx History Substitutions ) , 2105job control facilities (see 2106.Sx Jobs ) , 2107interactive file name 2108and user name completion (see 2109.Sx File Name Completion ) , 2110and a C-like syntax. 2111There are now many shells that also have these mechanisms, plus 2112a few more (and maybe some bugs too), which are available through the 2113usenet. 2114.Sh BUGS 2115When a command is restarted from a stop, 2116the shell prints the directory it started in if this is different 2117from the current directory; this can be misleading (i.e., wrong) 2118as the job may have changed directories internally. 2119.Pp 2120Shell builtin functions are not stoppable/restartable. 2121Command sequences of the form `a ; b ; c' are also not handled gracefully 2122when stopping is attempted. If you suspend `b', the shell will 2123immediately execute `c'. This is especially noticeable if this 2124expansion results from an 2125.Ar alias . 2126It suffices to place the sequence of commands in ()'s to force it to 2127a subshell, i.e., `( a ; b ; c )'. 2128.Pp 2129Control over tty output after processes are started is primitive; 2130perhaps this will inspire someone to work on a good virtual 2131terminal interface. In a virtual terminal interface much more 2132interesting things could be done with output control. 2133.Pp 2134Alias substitution is most often used to clumsily simulate shell procedures; 2135shell procedures should be provided instead of aliases. 2136.Pp 2137Commands within loops, prompted for by `?', are not placed on the 2138.Ic history 2139list. 2140Control structure should be parsed instead of being recognized as built-in 2141commands. This would allow control commands to be placed anywhere, 2142to be combined with `\&|', and to be used with `&' and `;' metasyntax. 2143.Pp 2144It should be possible to use the `:' modifiers on the output of command 2145substitutions. 2146.Pp 2147The way the 2148.Ic filec 2149facility is implemented is ugly and expensive. 2150