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