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