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