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