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