1.\" Copyright (c) 1980, 1990 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)csh.1 6.23 (Berkeley) 03/02/92 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 can be also 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 to not 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`\*(aa', `\*(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 subsequently. 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 which 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 (which 200may be a component of a pipeline, etc.) 201It is also possible to separate pipelines with `\&|\&|' or `&&' indicating, 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 which looks 214like: 215.Bd -filled -offset indent 216.Op 1 2171234 218.Ed 219.Pp 220indicating 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 indicate 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 then 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 244which does 245not generate a STOP signal until a program attempts to 246.Xr read 2 247it. 248This can usefully be typed ahead when you have prepared some commands 249for a job which you wish to stop after it has read them. 250.Pp 251A job being run in the background will stop if it tries to read 252from the terminal. Background jobs are normally allowed to produce output, 253but this can be disabled by giving the command ``stty tostop''. 254If you set this 255tty option, then background jobs will stop when they try to produce 256output like they do when they try to read input. 257.Pp 258There are several ways to refer to jobs in the shell. The character 259`%' introduces a job name. If you wish to refer to job number 1, you can 260name it as `%1'. Just naming a job brings it to the foreground; thus 261`%1' is a synonym for `fg %1', bringing job 1 back into the foreground. 262Similarly saying `%1 &' resumes job 1 in the background. 263Jobs can also be named by prefixes of the string typed in to start them, 264if these prefixes are unambiguous, thus `%ex' would normally restart 265a suspended 266.Xr ex 1 267job, if there were only one suspended job whose name began with 268the string `ex'. It is also possible to say `%?string' 269which specifies a job whose text contains 270.Ar string , 271if there is only one such job. 272.Pp 273The shell maintains a notion of the current and previous jobs. 274In output pertaining to jobs, the current job is marked with a `+' 275and the previous job with a `\-'. The abbreviation `%+' refers 276to the current job and `%\-' refers to the previous job. For close 277analogy with the syntax of the 278.Ar history 279mechanism (described below), 280`%%' is also a synonym for the current job. 281.Pp 282The job control mechanism requires that the 283.Xr stty 1 284option 285.Ic new 286be set. It is an artifact from a 287.Em new 288implementation 289of the 290tty driver which allows generation of interrupt characters from 291the keyboard to tell jobs to stop. See stty(1) for details 292on setting options in the new tty driver. 293.Ss Status reporting 294This shell learns immediately whenever a process changes state. 295It normally informs you whenever a job becomes blocked so that 296no further progress is possible, but only just before it prints 297a prompt. This is done so that it does not otherwise disturb your work. 298If, however, you set the shell variable 299.Ar notify , 300the shell will notify you immediately of changes of status in background 301jobs. 302There is also a shell command 303.Ar notify 304which marks a single process so that its status changes will be immediately 305reported. By default 306.Ar notify 307marks the current process; 308simply say `notify' after starting a background job to mark it. 309.Pp 310When you try to leave the shell while jobs are stopped, you will 311be warned that `You have stopped jobs.' You may use the 312.Ar jobs 313command to see what they are. If you do this or immediately try to 314exit again, the shell will not warn you a second time, and the suspended 315jobs will be terminated. 316.Ss File Name Completion 317When the file name completion feature is enabled by setting 318the shell variable 319.Ar filec 320(see 321.Ic set ) , 322.Nm csh 323will 324interactively complete file names and user names from unique 325prefixes, when they are input from the terminal followed by 326the escape character (the escape key, or control-[) 327For example, 328if the current directory looks like 329.Bd -literal -offset indent 330DSC.OLD bin cmd lib xmpl.c 331DSC.NEW chaosnet cmtest mail xmpl.o 332bench class dev mbox xmpl.out 333.Ed 334.Pp 335and the input is 336.Pp 337.Dl % vi ch<escape> 338.Pp 339.Nm csh 340will complete the prefix ``ch'' 341to the only matching file name ``chaosnet'', changing the input 342line to 343.Pp 344.Dl % vi chaosnet 345.Pp 346However, given 347.Pp 348.Dl % vi D<escape> 349.Pp 350.Nm csh 351will only expand the input to 352.Pp 353.Dl % vi DSC. 354.Pp 355and will sound the terminal bell to indicate that the expansion is 356incomplete, since there are two file names matching the prefix ``D''. 357.Pp 358If a partial file name is followed by the end-of-file character 359(usually control-D), then, instead of completing the name, 360.Nm csh 361will list all file names matching the prefix. For example, 362the input 363.Pp 364.Dl % vi D<control-D> 365.Pp 366causes all files beginning with ``D'' to be listed: 367.Pp 368.Dl DSC.NEW DSC.OLD 369.Pp 370while the input line remains unchanged. 371.Pp 372The same system of escape and end-of-file can also be used to 373expand partial user names, if the word to be completed 374(or listed) begins with the character ``~''. For example, 375typing 376.Pp 377.Dl cd ~ro<escape> 378.Pp 379may produce the expansion 380.Pp 381.Dl cd ~root 382.Pp 383The use of the terminal bell to signal errors or multiple matches 384can be inhibited by setting the variable 385.Ar nobeep . 386.Pp 387Normally, all files in the particular directory are candidates 388for name completion. Files with certain suffixes can be excluded 389from consideration by setting the variable 390.Ar fignore 391to the 392list of suffixes to be ignored. Thus, if 393.Ar fignore 394is set by 395the command 396.Pp 397.Dl % set fignore = (.o .out) 398.Pp 399then typing 400.Pp 401.Dl % vi x<escape> 402.Pp 403would result in the completion to 404.Pp 405.Dl % vi xmpl.c 406.Pp 407ignoring the files "xmpl.o" and "xmpl.out". 408However, if the only completion possible requires not ignoring these 409suffixes, then they are not ignored. In addition, 410.Ar fignore 411does not affect the listing of file names by control-D. All files 412are listed regardless of their suffixes. 413.Ss Substitutions 414We now describe the various transformations the shell performs on the 415input in the order in which they occur. 416.Ss History substitutions 417History substitutions place words from previous command input as portions 418of new commands, making it easy to repeat commands, repeat arguments 419of a previous command in the current command, or fix spelling mistakes 420in the previous command with little typing and a high degree of confidence. 421History substitutions begin with the character `!' and may begin 422.Ar anywhere 423in the input stream (with the proviso that they 424.Nm "do not" 425nest.) 426This `!' may be preceded by an `\e' to prevent its special meaning; for 427convenience, a `!' is passed unchanged when it is followed by a blank, 428tab, newline, `=' or `('. 429(History substitutions also occur when an input line begins with `\*(ua'. 430This special abbreviation will be described later.) 431Any input line which contains history substitution is echoed on the terminal 432before it is executed as it could have been typed without history substitution. 433.Pp 434Commands input from the terminal which consist of one or more words 435are saved on the history list. 436The history substitutions reintroduce sequences of words from these 437saved commands into the input stream. 438The size of which is controlled by the 439.Ar history 440variable; the previous command is always retained, regardless of its value. 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 modification, 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 essentially 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 modification 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 rather 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' quotes `&' also. 559A null 560.Ar l 561(" ") 562uses the previous string either from a 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. `!$'. 573In this case 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 which follow. 588Thus, after `ls \-ld ~paul' we might do `!{l}a' to do `ls \-ld ~paula', 589while `!la' would look for a command starting `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 Substitition 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 which 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 which 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 which 633.Ar pr \'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 which 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 subsequent 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 which 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 which 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. 711.br 712If 713.Ar name 714is not a shell variable, but is set in the environment, then 715that value is returned (but 716.Nm : 717modifiers and the other forms 718given below are not available in this case). 719.It $name Ns Op selector 720.It ${name Ns Op selector Ns } 721May be used to select only some of the words from the value of 722.Ar name . 723The selector is subjected to `$' substitution and may consist of a single 724number or two numbers separated by a `\-'. 725The first word of a variables value is numbered `1'. 726If the first number of a range is omitted it defaults to `1'. 727If the last member of a range is omitted it defaults to `$#name'. 728The selector `*' selects all words. 729It is not an error for a range to be empty if the second argument is omitted 730or in range. 731.It $#name 732.It ${#name} 733Gives the number of words in the variable. 734This is useful for later use in a 735`$argv[selector]'. 736.It $0 737Substitutes the name of the file from which command input is being read. 738An error occurs if the name is not known. 739.It $number 740.It ${number} 741Equivalent to 742`$argv[number]'. 743.It $* 744Equivalent to 745`$argv[*]'. 746The modifiers `:e', `:h', `:t', `:r', `:q' and `:x' may be applied to 747the substitutions above as may `:gh', `:gt' and `:gr'. 748If braces `{' '}' appear in the command form then the modifiers 749must appear within the braces. 750The current implementation allows only one `:' modifier on each `$' expansion. 751.El 752.Pp 753The following substitutions may not be modified with `:' modifiers. 754.Bl -tag -width Ds -compact -offset indent 755.It $?name 756.It ${?name} 757Substitutes the string `1' if name is set, `0' if it is not. 758.It $?0 759Substitutes `1' if the current input filename is known, `0' if it is not. 760.It $$ 761Substitute the (decimal) process number of the (parent) shell. 762.It $! 763Substiture the (decimal) process number of the last background process 764started by this shell. 765.It $< 766Substitutes a line from the standard 767input, with no further interpretation thereafter. It can be used 768to read from the keyboard in a shell script. 769.El 770.Ss Command and filename substitution 771The remaining substitutions, command and filename substitution, 772are applied selectively to the arguments of builtin commands. 773This means that portions of expressions which are not evaluated are 774not subjected to these expansions. 775For commands which are not internal to the shell, the command 776name is substituted separately from the argument list. 777This occurs very late, 778after input-output redirection is performed, and in a child 779of the main shell. 780.Ss Command substitution 781Command substitution is indicated by a command enclosed in `\*(ga'. 782The output from such a command is normally broken into separate words 783at blanks, tabs and newlines, with null words being discarded, 784this text then replacing the original string. 785Within `"'s, only newlines force new words; blanks and tabs are preserved. 786.Pp 787In any case, the single final newline does not force a new word. 788Note that it is thus possible for a command substitution to yield 789only part of a word, even if the command outputs a complete line. 790.Ss Filename substitution 791If a word contains any of the characters `*', `?', `[' or `{' 792or begins with the character `~', then that word is a candidate for 793filename substitution, also known as `globbing'. 794This word is then regarded as a pattern, and replaced with an alphabetically 795sorted list of file names which match the pattern. 796In a list of words specifying filename substitution it is an error for 797no pattern to match an existing file name, but it is not required 798for each pattern to match. 799Only the metacharacters `*', `?' and `[' imply pattern matching, 800the characters `~' and `{' being more akin to abbreviations. 801.Pp 802In matching filenames, the character `.' at the beginning of a filename 803or immediately following a `/', as well as the character `/' must 804be matched explicitly. 805The character `*' matches any string of characters, including the null 806string. 807The character `?' matches any single character. 808The sequence 809.Sq Op ... 810matches any one of the characters enclosed. 811Within 812.Sq Op ... , 813a pair of characters separated by `\-' matches any character lexically between 814the two. 815.Pp 816The character `~' at the beginning of a filename is used to refer to home 817directories. 818Standing alone, i.e. `~' it expands to the invokers home directory as reflected 819in the value of the variable 820.Ar home . 821When followed by a name consisting of letters, digits and `\-' characters 822the shell searches for a user with that name and substitutes their 823home directory; thus `~ken' might expand to `/usr/ken' and `~ken/chmach' 824to `/usr/ken/chmach'. 825If the character `~' is followed by a character other than a letter or `/' 826or appears not at the beginning of a word, 827it is left undisturbed. 828.Pp 829The metanotation `a{b,c,d}e' is a shorthand for `abe ace ade'. 830Left to right order is preserved, with results of matches being sorted 831separately at a low level to preserve this order. 832This construct may be nested. 833Thus `~source/s1/{oldls,ls}.c' expands to 834`/usr/source/s1/oldls.c /usr/source/s1/ls.c' 835whether or not these files exist without any chance of error 836if the home directory for `source' is `/usr/source'. 837Similarly `../{memo,*box}' might expand to `../memo ../box ../mbox'. 838(Note that `memo' was not sorted with the results of matching `*box'.) 839As a special case `{', `}' and `{}' are passed undisturbed. 840.Ss Input/output 841The standard input and standard output of a command may be redirected 842with the following syntax: 843.Pp 844.Bl -tag -width Ds -compact -offset indent 845.It < name 846Open file 847.Ar name 848(which is first variable, command and filename expanded) as the standard 849input. 850.It << word 851Read the shell input up to a line which is identical to 852.Ar word . 853.Ar Word 854is not subjected to variable, filename or command substitution, 855and each input line is compared to 856.Ar word 857before any substitutions are done on this input line. 858Unless a quoting `\e', `"', `\*(aa' or `\*(ga' appears in 859.Ar word 860variable and command substitution is performed on the intervening lines, 861allowing `\e' to quote `$', `\e' and `\*(ga'. 862Commands which are substituted have all blanks, tabs, and newlines 863preserved, except for the final newline which is dropped. 864The resultant text is placed in an anonymous temporary file which 865is given to the command as standard input. 866.It > name 867.It >! name 868.It >& name 869.It >&! name 870The file 871.Ar name 872is used as standard output. 873If the file does not exist then it is created; 874if the file exists, its is truncated, its previous contents being lost. 875.Pp 876If the variable 877.Ar noclobber 878is set, then the file must not exist or be a character special file (e.g. a 879terminal or `/dev/null') or an error results. 880This helps prevent accidental destruction of files. 881In this case the `!' forms can be used and suppress this check. 882.Pp 883The forms involving `&' route the diagnostic output into the specified 884file as well as the standard output. 885.Ar Name 886is expanded in the same way as `<' input filenames are. 887.It >> name 888.It >>& name 889.It >>! name 890.It >>&! name 891Uses file 892.Ar name 893as standard output like `>' 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; rather 906they 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 ; 914rather 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 921Diagnostic output may be directed through a pipe with the standard output. 922Simply use the form `\&|&' rather than just `\&|'. 923.Ss Expressions 924A number of the builtin commands (to be described subsequently) 925take expressions, in which the operators are similar to those of C, with 926the same precedence. 927These expressions appear in the 928.Nm @, 929.Ar exit , 930.Ar if , 931and 932.Ar while 933commands. 934The following operators are available: 935.Bd -ragged -offset indent 936\&|\&| && \&| *(ua & == != =~ !~ <= >= 937< > << >> + \- * / % ! ~ ( ) 938.Ed 939.Pp 940Here the precedence increases to the right, 941`==' `!=' `=~' and `!~', `<=' `>=' `<' and `>', `<<' and `>>', `+' and `\-', 942`*' `/' and `%' being, in groups, at the same level. 943The `==' `!=' `=~' and `!~' operators compare their arguments as strings; 944all others operate on numbers. 945The operators `=~' and `!~' are like `!=' and `==' except that the right 946hand side is a 947.Ar pattern 948(containing, e.g. `*'s, `?'s and instances of 949`[...]' 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 which 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 which 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 -ragged -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 of an expression and the variable 992.Ar status 993examined. 994.Ss Control flow 995The shell contains a number of commands which 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, due to 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 shells 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 \&% 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 up 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 which 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 indicating 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 1214which 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 1228rather than oldest first. 1229The 1230.Fl h 1231option causes the history list to be printed without leading numbers. 1232This is used to produce files suitable for sourceing using the \-h 1233option to 1234.Ic source . 1235.Pp 1236.It Ic if Pq 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, 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 to the first 1265.Ic else 1266are executed; otherwise if 1267.Ar expr2 1268is true then the commands 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; given the 1293.Fl l 1294options lists process id's in addition to the normal information. 1295.Pp 1296.It Ic kill % 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, saying just `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 which 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 scaling is `seconds', while `m' for minutes 1362or `h' for hours, or a time of the form `mm:ss' giving minutes 1363and seconds may be used. 1364.Pp 1365For both 1366.Ar resource 1367names and scale factors, unambiguous prefixes 1368of the names suffice. 1369.Pp 1370.It Ic login 1371Terminate a login shell, replacing it with an instance of 1372.Pa /bin/login. 1373This is one way to log off, included for compatibility with 1374.Xr sh 1 . 1375.Pp 1376.It Ic logout 1377Terminate a login shell. 1378Especially useful if 1379.Ic ignoreeof 1380is set. 1381.Pp 1382.It Ic nice 1383.It Ic nice Ar +number 1384.It Ic nice Ar command 1385.It Ic nice Ar +number command 1386The first form sets the 1387scheduling priority 1388for this shell to 4. 1389The second form sets the 1390priority 1391to the given 1392.Ar number . 1393The final two forms run command at priority 4 and 1394.Ar number 1395respectively. 1396The greater the number, the less cpu the process will get. 1397The super-user may specify negative priority by using `nice \-number ...'. 1398Command is always executed in a sub-shell, and the restrictions 1399placed on commands in simple 1400.Ic if 1401statements apply. 1402.Pp 1403.It Ic nohup 1404.It Ic nohup Ar command 1405The first form can be used in shell scripts to cause hangups to be 1406ignored for the remainder of the script. 1407The second form causes the specified command to be run with hangups 1408ignored. 1409All processes detached with `&' are effectively 1410.Ic nohup Ns \'ed . 1411.Pp 1412.It Ic notify 1413.It Ic notify % Ar job ... 1414Causes the shell to notify the user asynchronously when the status of the 1415current or specified jobs changes; normally notification is presented 1416before a prompt. This is automatic if the shell variable 1417.Ic notify 1418is set. 1419.Pp 1420.It Ic onintr 1421.It Ic onintr Fl 1422.It Ic onintr Ar label 1423Control the action of the shell on interrupts. 1424The first form restores the default action of the shell on interrupts 1425which is to terminate shell scripts or to return to the terminal command 1426input level. 1427The second form `onintr \-' causes all interrupts to be ignored. 1428The final form causes the shell to execute a `goto label' when 1429an interrupt is received or a child process terminates because 1430it was interrupted. 1431.Pp 1432In any case, if the shell is running detached and interrupts are 1433being ignored, all forms of 1434.Ic onintr 1435have no meaning and interrupts 1436continue to be ignored by the shell and all invoked commands. 1437Finally 1438.Ic onintr 1439statemements are ignored in the system startup files where interrupts 1440are disabled (/etc/csh.cshrc, /etc/csh.login). 1441.Pp 1442.It Ic popd 1443.It Ic popd Ar +n 1444Pops the directory stack, returning to the new top directory. 1445With an argument 1446.Ns \`+ Ar n Ns \' 1447discards the 1448.Ar n Ns \'th 1449entry in the stack. 1450The elements of the directory stack are numbered from 0 starting at the top. 1451.Pp 1452.It Ic pushd 1453.It Ic pushd Ar name 1454.It Ic pushd Ar n 1455With no arguments, 1456.Ic pushd 1457exchanges the top two elements of the directory stack. 1458Given a 1459.Ar name 1460argument, 1461.Ic pushd 1462changes to the new directory (ala 1463.Ic cd ) 1464and pushes the old current working directory 1465(as in 1466.Ic csw ) 1467onto the directory stack. 1468With a numeric argument, rotates the 1469.Ar n Ns \'th 1470argument of the directory 1471stack around to be the top element and changes to it. The members 1472of the directory stack are numbered from the top starting at 0. 1473.Pp 1474.It Ic rehash 1475Causes the internal hash table of the contents of the directories in 1476the 1477.Ic path 1478variable to be recomputed. This is needed if new commands are added 1479to directories in the 1480.Ic path 1481while you are logged in. This should only be necessary if you add 1482commands to one of your own directories, or if a systems programmer 1483changes the contents of one of the system directories. 1484.Pp 1485.It Ic repeat Ar count command 1486The specified 1487.Ar command 1488which is subject to the same restrictions 1489as the 1490.Ar command 1491in the one line 1492.Ic if 1493statement above, 1494is executed 1495.Ar count 1496times. 1497I/O redirections occur exactly once, even if 1498.Ar count 1499is 0. 1500.Pp 1501.It Ic set 1502.It Ic set Ar name 1503.It Ic set Ar name Ns =word 1504.It Ic set Ar name[index] Ns =word 1505.It Ic set Ar name Ns =(wordlist) 1506The first form of the command shows the value of all shell variables. 1507Variables which have other than a single word as value print as a parenthesized 1508word list. 1509The second form sets 1510.Ic name 1511to the null string. 1512The third form sets 1513.Ic name 1514to the single 1515.Ic word . 1516The fourth form sets 1517the 1518.Ar index Ns 'th 1519component of name to word; 1520this component must already exist. 1521The final form sets 1522.Ar name 1523to the list of words in 1524.Ar wordlist . 1525In all cases the value is command and filename expanded. 1526.Pp 1527These arguments may be repeated to set multiple values in a single set command. 1528Note however, that variable expansion happens for all arguments before any 1529setting occurs. 1530.Pp 1531.It Ic setenv 1532.It Ic setenv Ar name value 1533.It Ic setenv Ar name 1534The first form lists all current environment variables. 1535The last form sets the value of environment variable 1536.Ar name 1537to be 1538.Ar value , 1539a single string. The second form sets 1540.Ar name 1541to an empty string. 1542The most commonly used environment variable 1543.Ev USER , 1544.Ev TERM , 1545and 1546.Ev PATH 1547are automatically imported to and exported from the 1548.Nm csh 1549variables 1550.Ar user , 1551.Op Ar term , 1552and 1553.Ar path ; 1554there is no need to use 1555.Ic setenv 1556for these. 1557.Pp 1558.It Ic shift 1559.It Ic shift Ar variable 1560The members of 1561.Ic argv 1562are shifted to the left, discarding 1563.Ic argv Bq 1 . 1564It is an error for 1565.Ic argv 1566not to be set or to have less than one word as value. 1567The second form performs the same function on the specified variable. 1568.Pp 1569.It Ic source Ar name 1570.It Ic source Fl h Ar name 1571The shell reads commands from 1572.Ic name . 1573.Ic Source 1574commands may be nested; if they are nested too deeply the shell may 1575run out of file descriptors. 1576An error in a 1577.Ic source 1578at any level terminates all nested 1579.Ic source 1580commands. 1581Normally input during 1582.Ic source 1583commands is not placed on the history list; 1584the \-h option causes the commands to be placed in the 1585history list without being executed. 1586.Pp 1587.It Ic stop 1588.It Ic stop % Ns Ar job ... 1589Stops the current or specified job which is executing in the background. 1590.Pp 1591.It Ic suspend 1592Causes the shell to stop in its tracks, much as if it had been sent a stop 1593signal with 1594.Ic ^Z . 1595This is most often used to stop shells started by 1596.Xr su 1 . 1597.Pp 1598.It Ic switch Ar (string) 1599.It Ic case Ar str1 : 1600.It \ \ \ \ \&... 1601.It Ic \ \ \ \ breaksw 1602.It \ \ \ \ \&... 1603.It Ic default : 1604.It \ \ \ \ \&... 1605.It Ic \ \ \ \ breaksw 1606.It Ic endsw 1607Each case label is successively matched, against the specified 1608.Ar string 1609which is first command and filename expanded. 1610The file metacharacters `*', `?' and `[...]' 1611may be used in the case labels, 1612which are variable expanded. 1613If none of the labels match before a `default' label is found, then 1614the execution begins after the default label. 1615Each case label and the default label must appear at the beginning of a line. 1616The command 1617.Ic breaksw 1618causes execution to continue after the 1619.Ic endsw . 1620Otherwise control may fall through case labels and default labels as in C. 1621If no label matches and there is no default, execution continues after 1622the 1623.Ic endsw . 1624.Pp 1625.It Ic time 1626.It Ic time Ar command 1627With no argument, a summary of time used by this shell and its children 1628is printed. 1629If arguments are given 1630the specified simple command is timed and a time summary 1631as described under the 1632.Ic time 1633variable is printed. If necessary, an extra shell is created to print the time 1634statistic when the command completes. 1635.Pp 1636.It Ic umask 1637.It Ic umask Ar value 1638The file creation mask is displayed (first form) or set to the specified 1639value (second form). The mask is given in octal. Common values for 1640the mask are 002 giving all access to the group and read and execute 1641access to others or 022 giving all access except no write access for 1642users in the group or others. 1643.Pp 1644.It Ic unalias Ar pattern 1645All aliases whose names match the specified pattern are discarded. 1646Thus all aliases are removed by `unalias *'. 1647It is not an error for nothing to be 1648.Ic unaliased . 1649.Pp 1650.It Ic unhash 1651Use of the internal hash table to speed location of executed programs 1652is disabled. 1653.Pp 1654.It Ic unlimit 1655.It Ic unlimit Ar resource 1656.It Ic unlimit Fl h 1657.It Ic unlimit Fl h Ar resource 1658Removes the limitation on 1659.Ar resource . 1660If no 1661.Ar resource 1662is specified, then all 1663.Ar resource 1664limitations are removed. If 1665.Fl h 1666is given, the corresponding hard limits are removed. Only the 1667super-user may do this. 1668.Pp 1669.It Ic unset Ar pattern 1670All variables whose names match the specified pattern are removed. 1671Thus all variables are removed by `unset *'; this has noticeably 1672distasteful side-effects. 1673It is not an error for nothing to be 1674.Ic unset . 1675.Pp 1676.It Ic unsetenv Ar pattern 1677Removes all variables whose name match the specified pattern from the 1678environment. See also the 1679.Ic setenv 1680command above and 1681.Xr printenv 1 . 1682.Pp 1683.It Ic wait 1684All background jobs are waited for. 1685It the shell is interactive, then an interrupt can disrupt the wait, 1686at which time the shell prints names and job numbers of all jobs 1687known to be outstanding. 1688.It Ic which (command) 1689Displays the resolved command that will be executed by the shell. 1690.Pp 1691.It Ic while Ar (expr) 1692.It \&... 1693.It Ic end 1694While the specified expression evaluates non-zero, the commands between 1695the 1696.Ic while 1697and the matching end are evaluated. 1698.Ic Break 1699and 1700.Ic continue 1701may be used to terminate or continue the loop prematurely. 1702(The 1703.Ic while 1704and 1705.Ic end 1706must appear alone on their input lines.) 1707Prompting occurs here the first time through the loop as for the 1708.Ic foreach 1709statement if the input is a terminal. 1710.Pp 1711.It Ic % Ar job 1712Brings the specified job into the foreground. 1713.Pp 1714.It Ic % Ar job Ic & 1715Continues the specified job in the background. 1716.Pp 1717.It Ic @ 1718.It Ic @ Ns Ar name Ns = expr 1719.It Ic @ Ns Ar name[index] Ns = expr 1720The first form prints the values of all the shell variables. 1721The second form sets the specified 1722.Ar name 1723to the value of 1724.Ar expr . 1725If the expression contains `<', `>', `&' or `' then at least 1726this part of the expression must be placed within `(' `)'. 1727The third form assigns the value of 1728.Ar expr 1729to the 1730.Ar index Ns 'th 1731argument of 1732.Ar name . 1733Both 1734.Ar name 1735and its 1736.Ar index Ns 'th 1737component must already exist. 1738.El 1739.Pp 1740The operators `*=', `+=', etc are available as in C. 1741The space separating the name from the assignment operator is optional. 1742Spaces are, however, mandatory in separating components of 1743.Ar expr 1744which would otherwise be single words. 1745.Pp 1746Special postfix `++' and `\-\-' operators increment and decrement 1747.Ar name 1748respectively, i.e. `@ i++'. 1749.Ss Pre-defined and environment variables 1750The following variables have special meaning to the shell. 1751Of these, 1752.Ar argv , 1753.Ar cwd, 1754.Ar home , 1755.Ar path, 1756.Ar prompt , 1757.Ar shell 1758and 1759.Ar status 1760are always set by the shell. 1761Except for 1762.Ar cwd 1763and 1764.Ar status 1765this setting occurs only at initialization; 1766these variables will not then be modified unless this is done 1767explicitly by the user. 1768.Pp 1769This shell copies the environment variable 1770.Ev USER 1771into the variable 1772.Ar user , 1773.Ev TERM 1774into 1775.Ar term , 1776and 1777.Ev HOME 1778into 1779.Ar home , 1780and copies these back into the environment whenever the normal 1781shell variables are reset. 1782The environment variable 1783.Ev PATH 1784is likewise handled; it is not 1785necessary to worry about its setting other than in the file 1786.Ar \&.cshrc 1787as inferior 1788.Nm csh 1789processes will import the definition of 1790.Ar path 1791from the environment, and re-export it if you then change it. 1792.Bl -tag -width histchars 1793.It Ic argv 1794Set to the arguments to the shell, it is from this variable that 1795positional parameters are substituted, i.e. `$1' is replaced by 1796`$argv[1]', 1797etc. 1798.It Ic cdpath 1799Gives a list of alternate directories searched to find subdirectories 1800in 1801.Ar chdir 1802commands. 1803.It Ic cwd 1804The full pathname of the current directory. 1805.It Ic echo 1806Set when the 1807.Fl x 1808command line option is given. 1809Causes each command and its arguments 1810to be echoed just before it is executed. 1811For non-builtin commands all expansions occur before echoing. 1812Builtin commands are echoed before command and filename substitution, 1813since these substitutions are then done selectively. 1814.It Ic filec 1815Enable file name completion. 1816.It Ic histchars 1817Can be given a string value to change the characters used in history 1818substitution. The first character of its value is used as the 1819history substitution character, replacing the default character `!'. 1820The second character of its value replaces the character `\(ua' in 1821quick substitutions. 1822.It Ic histfile 1823Can be set to the pathname where history is going to be saved/restored. 1824.It Ic history 1825Can be given a numeric value to control the size of the history list. 1826Any command which has been referenced in this many events will not be 1827discarded. 1828Too large values of 1829.Ar history 1830may run the shell out of memory. 1831The last executed command is always saved on the history list. 1832.It Ic home 1833The home directory of the invoker, initialized from the environment. 1834The filename expansion of 1835.Sq Pa ~ 1836refers to this variable. 1837.It Ic ignoreeof 1838If set the shell ignores 1839end-of-file from input devices which are terminals. 1840This prevents shells from accidentally being killed by control-D's. 1841.It Ic mail 1842The files where the shell checks for mail. 1843This is done after each command completion which will result in a prompt, 1844if a specified interval has elapsed. 1845The shell says `You have new mail.' 1846if the file exists with an access time not greater than its modify time. 1847.Pp 1848If the first word of the value of 1849.Ar mail 1850is numeric it specifies a different mail checking interval, in seconds, 1851than the default, which is 10 minutes. 1852.Pp 1853If multiple mail files are specified, then the shell says 1854`New mail in 1855.Ar name Ns ' 1856when there is mail in the file 1857.Ar name . 1858.It Ic noclobber 1859As described in the section on 1860.Sx Input/output , 1861restrictions are placed on output redirection to insure that 1862files are not accidentally destroyed, and that `>>' redirections 1863refer to existing files. 1864.It Ic noglob 1865If set, filename expansion is inhibited. 1866This is most useful in shell scripts which are not dealing with filenames, 1867or after a list of filenames has been obtained and further expansions 1868are not desirable. 1869.It Ic nonomatch 1870If set, it is not an error for a filename expansion to not match any 1871existing files; rather the primitive pattern is returned. 1872It is still an error for the primitive pattern to be malformed, i.e. 1873`echo [' 1874still gives an error. 1875.It Ic notify 1876If set, the shell notifies asynchronously of job completions. The 1877default is to rather present job completions just before printing 1878a prompt. 1879.It Ic path 1880Each word of the path variable specifies a directory in which 1881commands are to be sought for execution. 1882A null word specifies the current directory. 1883If there is no 1884.Ar path 1885variable then only full path names will execute. 1886The usual search path is `.', `/bin' and `/usr/bin', but this 1887may vary from system to system. 1888For the super-user the default search path is `/etc', `/bin' and `/usr/bin'. 1889A shell which is given neither the 1890.Fl c 1891nor the 1892.Fl t 1893option will normally hash the contents of the directories in the 1894.Ar path 1895variable after reading 1896.Ar \&.cshrc , 1897and each time the 1898.Ar path 1899variable is reset. If new commands are added to these directories 1900while the shell is active, it may be necessary to do a 1901.Ic rehash 1902or the commands may not be found. 1903.It Ic prompt 1904The string which is printed before each command is read from 1905an interactive terminal input. 1906If a `!' appears in the string it will be replaced by the current event number 1907unless a preceding `\e' is given. 1908Default is `% ', or `# ' for the super-user. 1909.It Ic savehist 1910Is given a numeric value to control the number of entries of the 1911history list that are saved in ~/.history when the user logs out. 1912Any command which has been referenced in this many events will be saved. 1913During start up the shell sources ~/.history into the history list 1914enabling history to be saved across logins. 1915Too large values of 1916.Ar savehist 1917will slow down the shell during start up. 1918If 1919.Ar savehist 1920is just set, the shell will use the value of 1921.Ar history. 1922.It Ic shell 1923The file in which the shell resides. 1924This is used in forking shells to interpret files which have execute 1925bits set, but which are not executable by the system. 1926(See the description of 1927.Sx Non-builtin Command Execution 1928below.) 1929Initialized to the (system-dependent) home of the shell. 1930.It Ic status 1931The status returned by the last command. 1932If it terminated abnormally, then 0200 is added to the status. 1933Builtin commands which fail return exit status `1', 1934all other builtin commands set status `0'. 1935.It Ic time 1936Controls automatic timing of commands. 1937If set, then any command which takes more than this many cpu seconds 1938will cause a line giving user, system, and real times and a utilization 1939percentage which is the ratio of user plus system times to real time 1940to be printed when it terminates. 1941.It Ic verbose 1942Set by the 1943.Fl v 1944command line option, causes the words of each command to be printed 1945after history substitution. 1946.El 1947.Ss Non-builtin command execution 1948When a command to be executed is found to not be a builtin command 1949the shell attempts to execute the command via 1950.Xr execve 2 . 1951Each word in the variable 1952.Ar path 1953names a directory from which the shell will attempt to execute the command. 1954If it is given neither a 1955.Fl c 1956nor a 1957.Fl t 1958option, the shell will hash the names in these directories into an internal 1959table so that it will only try an 1960.Ic exec 1961in a directory if there is a possibility that the command resides there. 1962This greatly speeds command location when a large number of directories 1963are present in the search path. 1964If this mechanism has been turned off (via 1965.Ic unhash ) , 1966or if the shell was given a 1967.Fl c 1968or 1969.Fl t 1970argument, and in any case for each directory component of 1971.Ar path 1972which does not begin with a `/', 1973the shell concatenates with the given command name to form a path name 1974of a file which it then attempts to execute. 1975.Pp 1976Parenthesized commands are always executed in a subshell. 1977Thus 1978.Pp 1979.Dl (cd ; pwd) ; pwd 1980.Pp 1981prints the 1982.Ar home 1983directory; leaving you where you were (printing this after the home directory), 1984while 1985.Pp 1986.Dl cd ; pwd 1987.Pp 1988leaves you in the 1989.Ar home 1990directory. 1991Parenthesized commands are most often used to prevent 1992.Ic chdir 1993from affecting the current shell. 1994.Pp 1995If the file has execute permissions but is not an 1996executable binary to the system, then it is assumed to be a 1997file containing shell commands and a new shell is spawned to read it. 1998.Pp 1999If there is an 2000.Ic alias 2001for 2002.Ic shell 2003then the words of the alias will be prepended to the argument list to form 2004the shell command. 2005The first word of the 2006.Ic alias 2007should be the full path name of the shell 2008(e.g. `$shell'). 2009Note that this is a special, late occurring, case of 2010.Ic alias 2011substitution, 2012and only allows words to be prepended to the argument list without modification. 2013.Ss Signal handling 2014The shell normally ignores 2015.Ar quit 2016signals. 2017Jobs running detached (either by 2018.Ic \&& 2019or the 2020.Ic bg 2021or 2022.Ic %... & 2023commands) are immune to signals generated from the keyboard, including 2024hangups. 2025Other signals have the values which the shell inherited from its parent. 2026The shell's handling of interrupts and terminate signals 2027in shell scripts can be controlled by 2028.Ic onintr . 2029Login shells catch the 2030.Ar terminate 2031signal; otherwise this signal is passed on to children from the state in the 2032shell's parent. 2033In no case are interrupts allowed when a login shell is reading the file 2034.Pa \&.logout . 2035.Sh AUTHOR 2036William Joy. 2037Job control and directory stack features first implemented by J.E. Kulp of 2038IIASA, Laxenburg, Austria, 2039with different syntax than that used now. 2040File name completion code written by Ken Greer, HP Labs. 2041Eight-bit implementation Christos S. Zoulas, Cornell University. 2042.Sh FILES 2043.Bl -tag -width /etc/passwd -compact 2044.It Pa ~/.cshrc 2045Read at beginning of execution by each shell. 2046.It Pa ~/.login 2047Read by login shell, after `.cshrc' at login. 2048.It Pa ~/.logout 2049Read by login shell, at logout. 2050.It Pa /bin/sh 2051Standard shell, for shell scripts not starting with a `#'. 2052.It Pa /tmp/sh* 2053Temporary file for `<<'. 2054.It Pa /etc/passwd 2055Source of home directories for `~name'. 2056.El 2057.Sh LIMITATIONS 2058Word lengths \- 2059Words can be no longer than 1024 characters. 2060The system limits argument lists to 10240 characters. 2061The number of arguments to a command which involves filename expansion 2062is limited to 1/6'th the number of characters allowed in an argument list. 2063Command substitutions may substitute no more characters than are 2064allowed in an argument list. 2065To detect looping, the shell restricts the number of 2066.Ic alias 2067substitutions on a single line to 20. 2068.Sh SEE ALSO 2069.Xr sh 1 , 2070.Xr access 2 , 2071.Xr execve 2 , 2072.Xr fork 2 , 2073.Xr killpg 2 , 2074.Xr pipe 2 , 2075.Xr sigvec 2 , 2076.Xr umask 2 , 2077.Xr setrlimit 2 , 2078.Xr wait 2 , 2079.Xr tty 4 , 2080.Xr a.out 5 , 2081.Xr environ 7 , 2082.br 2083.Em An introduction to the C shell 2084.Sh HISTORY 2085.Nm Csh 2086appeared in 2087.Bx 3 . 2088It 2089was a first implementation of a command language interpreter 2090incorporating a history mechanism (see 2091.Sx History Substitutions ) , 2092job control facilities (see 2093.Sx Jobs ) , 2094interactive file name 2095and user name completion (see 2096.Sx File Name Completion ) , 2097and a C-like syntax. 2098There are now many shells which also have these mechanisms, plus 2099a few more (and maybe some bugs too), which are available thru the 2100usenet, or with 2101.Bx 2102as contributed software like the 2103.Xr ksh korn\ shell . 2104.Sh BUGS 2105When a command is restarted from a stop, 2106the shell prints the directory it started in if this is different 2107from the current directory; this can be misleading (i.e. wrong) 2108as the job may have changed directories internally. 2109.Pp 2110Shell builtin functions are not stoppable/restartable. 2111Command sequences of the form `a ; b ; c' are also not handled gracefully 2112when stopping is attempted. If you suspend `b', the shell will then 2113immediately execute `c'. This is especially noticeable if this 2114expansion results from an 2115.Ar alias . 2116It suffices to place the sequence of commands in ()'s to force it to 2117a subshell, i.e. `( a ; b ; c )'. 2118.Pp 2119Control over tty output after processes are started is primitive; 2120perhaps this will inspire someone to work on a good virtual 2121terminal interface. In a virtual terminal interface much more 2122interesting things could be done with output control. 2123.Pp 2124Alias substitution is most often used to clumsily simulate shell procedures; 2125shell procedures should be provided rather than aliases. 2126.Pp 2127Commands within loops, prompted for by `?', are not placed in the 2128.Ic history 2129list. 2130Control structure should be parsed rather than being recognized as built-in 2131commands. This would allow control commands to be placed anywhere, 2132to be combined with `\&|', and to be used with `&' and `;' metasyntax. 2133.Pp 2134It should be possible to use the `:' modifiers on the output of command 2135substitutions. 2136.Pp 2137The way the 2138.Ic filec 2139facility is implemented is ugly and expensive. 2140