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