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