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