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