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