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