csh(C) 06 January 1993 csh(C) Name csh - invoke a shell command interpreter with C-like syntax Syntax csh [ -cefinstvVxX ] [ arg ... ] Description csh is a command language interpreter. When it is first invoked, csh executes commands from the file .cshrc, located in the home directory of the user. If it is a login shell, it then executes commands from the file .login (in the same directory). Subsequently, if it is running in interactive mode, csh reads commands from the terminal, prompting the user for each new line by printing a ``%''. Arguments to the shell, and the use of the shell to process files containing command scripts, will be described later. The shell repeatedly performs the following actions: a line of command input is read and broken into words. This sequence of words is placed on the command history list and then parsed. Finally, each command in the current line is executed. When a login shell terminates, it executes commands from the file .logout in the user's home directory. Lexical structure The shell splits input lines into words at blanks and tabs with the fol- lowing exceptions. The characters & | ; < > ( and ) are treated as separate words. Some of these characters can be paired up; the following pairs &&, ||, <<, >> are treated as single words. In order to use these metacharacters within other words, their special meaning must be suppressed by preceding them with a backslash (\). A newline preceded by a ``\'' is equivalent to a blank. In addition, strings enclosed in matched pairs of quotations, (', ` or "), form parts of a word; metacharacters in these strings, including blanks and tabs, are not treated as separate words. The semantics of quoted strings are described below. Within quoted strings delimited by pairs of (') or (") characters, a newline preceded by a ``\'' gives a true newline character. If the shell reads the character ``#'' in its input, it treats the rest of the current line (that is, all the text to the right of the ``#'') as a comment, and ignores it. The ``#'' character loses this special mean- ing if it is preceded by a backslash character (\) or placed inside quo- tation marks (`, ', or "). Commands A simple command is a sequence of words, the first of which specifies the command to be executed. A simple command or a sequence of simple com- mands separated by ``|'' characters (pipes) forms a pipeline. The output from each command in a pipeline is used as the input to the next command. Sequences of pipelines may be separated by semi-colons (;); the elements of such a sequence are executed sequentially. A sequence of pipelines may be executed without waiting for it to terminate by ending the command line with an ampersand character (&). Such a sequence is protected from termination by hangup signals sent by the shell; the nohup command need not be used. Any of the above commands may be placed in parentheses to form a new sim- ple command (which in turn may be used as a component of a pipeline or some other more complex command.) It is also possible to separate pipe- lines with the ``&&'' or ``||'' expressions: these stand for logical-OR and logical-AND respectively. (Due to an historical bug, csh assigns these symbols the opposite meaning to that assumed by the ``C'' program- ming language and other UNIX utilities.) Use of these expressions makes the execution of the second pipeline conditional upon the success (logical-AND) or failure (logical-OR) of the first. (See ``Expressions'' for more information.) Substitutions The following sections describe the various transformations the shell performs on the input in the order in which they are carried out. History substitutions History substitutions can be used to reintroduce sequences of words from previous commands, possibly altering them in the process. Thus, history substitutions provide a general redo facility. History substitutions begin with the character ``!'' and may begin any- where in the input stream unless a history substitution is already in progress. A ``!'' preceded by a backslash (\), or followed by a space, tab, newline, ``='' or ``('', is treated as a literal ``!'' and its spe- cial meaning is suppressed. History substitutions may also occur when an input line begins with ``^''. This special abbreviation will be described later. The text of any input line containing a history substitution is echoed on the terminal after the substitution has been carried out, so that the user can see the literal command that is being executed. Commands entered at the terminal and consisting of one or more words are saved on the history list, the size of which is controlled by the history variable. The previous command is always retained. Commands are assigned numbers incrementally, starting with``1'' (the first command executed under the current csh). For example, enter the command: history This internal command causes csh to print a list of the commands stored on the history list, along with their event numbers. Now, consider the following (sample) output from the history command: 9 write michael 10 ex write.c 11 cat oldwrite.c 12 diff *write.c It is not usually necessary to use event numbers, but the current event number can be made part of the prompt by placing a ``!'' in the prompt string. If the current event (the current command line) is 13, we can refer to previous command lines in several ways: By event number: !11 to re-run cat oldwrite.c By relative event number: !-2 to go back two events; this will also re-run cat oldwrite.c By part of a command: !d will re-run the most recent command starting with a ``d'', in this case diff *write.c, while: !?mic? will re-run the most recent command containing the string ``mic''; write michael These forms simply reproduce the words of the specified event, each separated by a single blank. The special case ``!!'' refers to the pre- vious command; thus the history substitution ``!!'' means ``repeat the last command.'' The form ``!#'' references the current command (the one being entered on the current line). It allows a word to be selected from further left in the line, for example to avoid retyping a long name, as in ``!#:1''. To select words from an event, we can follow the event specification by a colon (:) and a designator for the desired words. The words of an input line are numbered from 0, the first (usually command) word being 0, the second word (first argument) being 1, and so on. The basic word designa- tors are: 0 First (command) word n nth argument ^ First argument, that is, 1 $ Last argument % Word matched by (immediately preceding) ?s? search x-y Range of words -y Abbreviates 0-y * Abbreviates ^-$, or nothing if only 1 word in event x* Abbreviates x-$ x- Like x* but omitting word $ The ``:'' separating the event specification from the word designator can be omitted if the argument selector begins with a ^, $, *, - or %. After the optional word designator, a sequence of modifiers can be placed, each preceded by a colon. The following modifiers are defined: h Removes a trailing pathname component r Removes a trailing .xxx component e Returns the trailing .xxx pathname component s/l/r/ Substitutes r for l t Removes all leading pathname components & Repeats the previous substitution g Applies the change globally, prefixing the above p Prints the new command but does not execute it q Quotes the substituted words, preventing substitutions x Like q, but breaks into words at blanks, tabs, and newlines Unless preceded by a ``g'', the modification is applied only to the first modifiable word. In any case it is an error for no word to be applica- ble. The left sides of substitutions are not regular expressions like those recognized by the editors, but rather strings. Any character may be used as the delimiter instead of ``/''; if it is necessary to include an instance of the delimiter character within one of the substitution strings, its special meaning may be removed by preceding it with a ``\''. An ampersand character (&) in the right side of a substitution is replaced by the text from the left side of the substitution. An amper- sand preceded by a backslash (\&) is treated as a literal ampersand (&) with no special meaning. A null l uses the previous string either from an l or from a contextual scan string s in ``!?s?''. The trailing delim- iter in the substitution may be omitted if a newline follows immediately, as may the trailing ``?'' in a contextual scan. A history reference may be given without an event specification (for example, !$). It is assumed that the reference is to the previous com- mand unless a history substitution precedes it on the same line, in which case it is assumed to refer to the last event substitution. Thus !?foo?^!$ gives the first and last arguments from the command matching ?foo?. A special abbreviation of a history reference occurs when the first non- blank character of an input line is a ``^''. This is equivalent to !:s^, providing a convenient shorthand for substitutions on the text of the previous line. Thus ^lb^lib fixes the spelling of lib in the previous command. Finally, a history substitution may be surrounded with ``{'' and ``}'' if necessary to insulate it from the characters that follow. Thus, after ls -ld ~paul we might do !{l}a to do ls -ld ~paula, while !la would look for a command starting la. Quotations with ' and '' Quoted (') or double quoted (") strings are exempt from some or all of the substitutions. Strings enclosed in single quotes are not subject to interpretation. Strings enclosed in double quotes are subject to vari- able and command expansion. Since history (!) substitution occurs within all quotes, you must escape ``!'' with a backslash (\) even within quotes if you want to prevent history substitution. In both cases, the resulting text becomes (all or part of) a single word; only in one special case (see ``Command substitution'' below) does a dou- ble quoted string yield parts of more than one word; single quoted strings never do. Alias substitution The shell maintains a list of aliases which can be established, displayed and modified by the alias and unalias commands. After a command line is scanned, it is parsed into distinct commands and the first word of each command, left-to-right, is checked to see if it has an alias. If it does, then the text of the alias for that command is reread, and the his- tory mechanism is applied to it as though that command were the previous input line. The resulting words replace the command and argument list. If no reference is made to the history list, then the argument list is left unchanged. Thus, if the alias for ``ls'' is ``ls -l'', the command ``ls /usr'' would map to ``ls -l /usr''. Similarly if the alias for ``lookup'' was ``grep \!^ /etc/passwd'', then ``lookup bill'' would map to ``grep bill /etc/passwd''. If an alias is found, the word transformation of the input text is per- formed and the aliasing process begins again on the newly generated input line. Looping is prevented by flagging the first word of the old text; if the first word of the new text is the same, further aliasing is prevented. Other loops are detected and cause an error. Note that the mechanism allows aliases to introduce parser metasyntax. Thus we can say: alias print 'pr :* | lpr' to make a command that paginates its arguments to the lineprinter. There are four csh aliases distributed. These are pushd, popd, swapd, and flipd. These aliases maintain a directory stack. pushd dir Pushes the current directory onto the top of the directory stack, then changes to the directory dir. popd Changes to the directory at the top of the stack, then removes (pops) the top directory from the stack, and announces the current directory. swapd Swaps the top two directories on the stack. The directory on the top becomes the second to the top, and the second to the top directory becomes the top directory. flipd Flips between two directories, the current directory and the top directory on the stack. If you are currently in dir1, and dir2 is on the top of the stack, when flipd is invoked you change to dir2 and dir1 is replaced as the top directory on the stack. When flipd is again invoked, you change to dir1 and dir2 is again the top directory on the stack. Variable substitution The shell maintains a set of variables, each of which has a list of zero or more words as its value. Some of these variables are set by the shell or referred to by it. For instance, the argv variable is an image of the shell's argument list, and words of this variable's value are referred to in special ways. The values of variables may be displayed and changed by using the set and unset commands. Of the variables referred to by the shell a number are toggles; the shell does not care what their value is, only whether they are set or not. For instance, the verbose variable is a toggle which causes command input to be echoed. The setting of this variable results from the -v command line option. Other operations treat variables numerically. The at-sign (@) command permits numeric calculations to be performed and the result assigned to a variable. However, variable values are always represented as (zero or more) strings. For the purposes of numeric operations, the null string is considered to be zero, and the second and subsequent words of multi- word values are ignored. After the input line is aliased and parsed, and before each command is executed, variable substitution is performed, keyed by dollar sign ($) characters. This expansion can be prevented by preceding the dollar sign with a backslash (\) except within double quotation marks (") where it always occurs, and within single quotation marks (') where it never occurs. Strings quoted by back quotation marks (`) are interpreted later (see ``Command substitution'' below) so dollar sign substitution does not occur there until later, if at all. A dollar sign is passed unchanged if followed by a blank, tab, or end-of-line. Input and output redirections are recognized before variable expansion, and are expanded separately. Otherwise, the command name and entire argument list are expanded together. It is thus possible for the first (command) word to generate more than one word, the first of which becomes the command name, and the rest of which become arguments. Unless enclosed in double quotation marks or given the :q modifier, the results of variable substitution may eventually be subject to command and filename substitution. Within double quotation marks ("), a variable whose value consists of multiple words expands to a portion of a single word, with the words of the variable's value separated by blanks. When the :q modifier is applied to a substitution, the variable expands to multiple words with each word separated by a blank and quoted to prevent later command or filename substitution. The following sequences are provided for introducing variable values into the shell input. Except as noted, it is an error to reference a variable which is not set. $name ${name} Are replaced by the words of the value of variable name, each separated by a blank. Braces insulate name from following characters which would otherwise be part of it. Shell vari- ables have names consisting of up to 20 letters, digits, and underscores. If name is not a shell variable, but is set in the environ- ment, then that value is returned (but : modifiers and the other forms given below are not available in this case). $name[selector] ${name[selector]} May be used to select only some of the words from the value of name. The selector is subjected to $ substitution and may consist of a single number or two numbers separated by a ``- ''. The first word of a variable's value is numbered 1. If the first number of a range is omitted it defaults to 1. If the last member of a range is omitted it defaults to $#name. The selector ``*'' selects all words. It is not an error for a range to be empty if the second argument is omitted or in range. $#name ${#name} Gives the number of words in the variable. This is useful for later use in a [selector]. $0 Substitutes the name of the file from which command input is being read. An error occurs if the name is not known. $number ${number} Equivalent to $argv[number]. $* Equivalent to $argv[*]. The modifiers :h, :t, :r, :q and :x may be applied to the substitutions above as may :gh, :gt and :gr. If braces ({ and }) appear in the command form then the modifiers must appear within the braces. Only one ``:'' modifier is allowed on each ``$'' expansion. The following substitutions may not be modified with ``:'' modifiers. $?name ${?name} Substitutes the string 1 if name is set, 0 if it is not. $?0 Substitutes 1 if the current input filename is known, 0 if it is not. $$ Substitutes the (decimal) process number of the (parent) shell. Command and filename substitution Command and filename substitution are applied selectively to the argu- ments of built-in commands. This means that portions of expressions which are not evaluated are not subjected to these expansions. For com- mands which are not internal to the shell, the command name is substi- tuted separately from the argument list. This occurs very late, after input-output redirection is performed, and in a child of the main shell. Command substitution Command substitution is indicated by a command enclosed in back quotation marks (`). The output from such a command is normally broken into separate words at blanks, tabs and newlines, with null words being dis- carded. This text then replaces the original string. Within double quo- tation marks, only newlines force new words; blanks and tabs are preserved. In any case, the single final newline does not force a new word. Note that it is possible for a command substitution to yield only part of a word, even if the command outputs a complete line. Filename substitution If a word contains any of the characters * ? [ { or begins with the char- acter ``~'', then that word is a candidate for filename substitution, also known as globbing. This word is then regarded as a pattern, and is replaced with an alphabetically sorted list of filenames which match the pattern. In a list of words specifying filename substitution it is an error for no pattern to match an existing filename, but it is not required for each pattern to match. Only the metacharacters ``*'', ``?'', and ``['' imply pattern matching. The characters ``~'' and ``{'' are more akin to abbreviations. In matching filenames, the character ``.'' at the beginning of a filename or immediately following a ``/'', as well as the character ``/'' must be matched explicitly. The character ``*'' matches any string of charac- ters, including the null string. The character ``?'' matches any single character. The sequence within square brackets ([ and ]) matches any one of the characters enclosed. Within square brackets, a pair of characters separated by ``-'' matches any character lexically between the two. The character ``~'' at the beginning of a filename is used to refer to home directories. Standing alone, it expands to the invoker's home directory contained in the variable HOME. When ``~'' is followed by a name consisting of letters, digits, and underscore characters (like_this), the shell searches for a user with that name and substitutes their home directory; thus ~ken might expand to /usr/ken and ~ken/chmach to /usr/ken/chmach. If the character ``~'' is followed by a character other than a letter or ``/'', or if it does not appear at the beginning of a word, it is left unchanged. The metanotation a{b,c,d}e is a shorthand for abe ace ade. Left to right order is preserved, with results of matches being sorted separately at a low level to preserve this order. Thus ~source/s1/{oldls,ls}.c expands to /usr/source/s1/oldls.c /usr/source/s1/ls.c, whether or not these files exist, assuming that the home directory for source is /usr/source. Simi- larly ../{memo,*box} might expand to ../memo ../box ../mbox. (Note that memo was not sorted with the results of matching *box.) As a special case ``{'', ``}'' and ``{}'' are passed unchanged. This construct can be nested. Spelling checker If the local variable cdspell has been set, the shell checks spelling whenever you use cd to change directories. For example, if you change to a different directory using cd and misspell the directory name, the shell responds with an alternative spelling of an existing directory. Enter ``y'' and press <Return> (or just press <Return>) to change to the offered directory. If the offered spelling is incorrect, enter ``n'', then retype the command line. In this example the csh response is bold- faced: % cd /usr/spol/uucp /usr/spool/uucp? y ok Input/output The standard input and standard output of a command may be redirected with the following syntax: < name Opens file name (after variable, command and filename expan- sion) as the standard input. << word Reads the shell input up to a line which is identical to word. word is not subjected to variable, filename or command substitution, and each input line is compared to word before any substitutions are done on this input line. Unless a quoting backslash, double, or single quotation mark, or a back quotation mark appears in word, variable and command substitution is performed on the intervening lines, allowing ``\'' to quote ``$'', ``\'' and ```''. Commands which are substituted have all blanks, tabs, and newlines preserved, except for the final newline which is dropped. The resulting text is placed in an anonymous temporary file which is given to the command as standard input. > name >! name >& name >&! name The file name is used as standard output. If the file does not exist, then it is created; if the file exists, it is overwritten. If the variable noclobber is set, then an error results if the file already exists or if it is not a character special file (for example, a terminal or /dev/null). This helps prevent accidental destruction of files. In this case, the ``!'' forms can be used to suppress this check. The forms involving ``&'' route the standard error into the specified file as well as the standard output. name is expanded in the same way as ``<'' input filenames are. >> name >>& name >>! name >>&! name Uses file name as standard output like ``>'' but places out- put at the end of the file. If the variable noclobber is set, then it is an error for the file not to exist unless one of the ``!'' forms is given. Otherwise similar to ``>''. If a command is run in the background (followed by ``&'') then the default standard input for the command is the empty file /dev/null. Oth- erwise, the command receives the input and output parameters from its parent shell. Thus, unlike some previous shells, commands run from a file of shell commands have no access to the text of the commands by default; rather they receive the original standard input of the shell. The << mechanism should be used to present inline data. This permits shell command scripts to function as components of pipelines and allows the shell to block read its input. The standard error may be directed through a pipe with the standard out- put. Simply use the form ``|&'' rather than just ``|''. Expressions A number of the built-in commands (to be described later) take expres- sions, in which the operators are similar to those of C, with the same precedence. These expressions appear in the @, exit, if, and while com- mands. The following operators are available: || && | ^ & == != <= >= < > << >> + - * / % ! ~ ( ) Here the precedence increases to the right, == and !=, <=, >=, <, and >, << and >>, + and -, * / and % being, in groups, at the same level. The == and != operators compare their arguments as strings, all others operate on numbers. Strings which begin with ``0'' are considered octal numbers. Null or missing arguments are considered 0. The result of all expressions are strings, which represent decimal numbers. Note that no two components of an expression can appear in the same word unless the word is adjacent to components of expressions that are syntactically sig- nificant to the parser (& | < > ( )). These components should be sur- rounded by spaces. Also available in expressions as primitive operands are command execu- tions enclosed in ``{'' and ``}'' and file enquiries of the form -l name where l is one of: r Read access w Write access x Execute access e Existence o Ownership z Zero size f Plain file d Directory Command and filename expansion is applied to the specified name, then the result is tested to see if it has the specified relationship to the real user. If the file does not exist or is inaccessible then all enquiries return false, that is 0. Command executions succeed, returning true, that is 1, if the command exits with status 0, otherwise they fail, returning false, that is 0. If more detailed status information is required then the command should be executed outside of an expression and the variable status examined. Control flow The shell contains a number of commands which can be used to regulate the flow of control in command files (shell scripts) and (in limited but use- ful ways) from terminal input. Due to the implementation, some restric- tions are placed on the word placement for the foreach, switch, and while statements, as well as the if-then-else form of the if statement. Please pay careful attention to these restrictions in the descriptions in the next section. If the shell's input is not seekable, the shell buffers up input whenever a loop is being read and performs seeks in this internal buffer to accom- plish the rereading implied by the loop. (To the extent that this allows, backward goto commands will succeed on nonseekable inputs.) Built-in commands Built-in commands are executed within the shell. If a built-in command occurs as any component of a pipeline except the last, then it is exe- cuted in a subshell. alias alias name alias name wordlist The first form prints all aliases. The second form prints the alias for name. The final form assigns the specified wordlist as the alias of name. wordlist is the command; filename substitution may be applied to wordlist. name is not allowed to be alias or unalias. break Causes execution to resume after the end of the nearest enclosing foreach or while statement. The remaining commands on the current line are executed. Multilevel breaks are thus possible by writing them all on one line. breaksw Causes a break from a switch, resuming after the endsw. case label: This is part of the switch statement discussed below. cd cd name chdir chdir name Changes the shell's working directory to directory name. If no argument is given, it then changes to the home directory of the user. If name is not found as a subdirectory of the current directory (and does not begin with ``/'', ``./'', or ``../''), then each component of the variable cdpath is checked to see if it has a subdirectory name. Finally, if all else fails but name is a shell variable whose value begins with ``/'', then this is tried to see if it is a directory. If cdspell has been set, the shell runs a spelling check as follows. If the shell is reading its commands from a termi- nal, and the specified directory does not exist (or some com- ponent cannot be searched), spelling correction is applied to each component of directory in a search for the ``correct'' name. The shell then asks whether or not to try and change the directory to the corrected directory name; an answer of n means ``no,'' and anything else is taken as ``yes.'' continue Continues execution of the nearest enclosing while or foreach. The rest of the commands on the current line are executed. default: Labels the default case in a switch statement. The default should come after all case labels. echo wordlist The specified words are written to the shell's standard out- put. A ``\c'' causes the echo to complete without printing a newline. A ``\n'' in wordlist causes a newline to be printed. Otherwise the words are echoed, separated by spaces. else end endif endsw See the description of the foreach, if, switch, and while statements below. exec command The specified command is executed in place of the current shell. exit exit (expr) The shell exits either with the value of the status variable (first form) or with the value of the specified expr (second form). foreach name (wordlist) ... end The variable name is successively set to each member of wordlist and the sequence of commands between this command and the matching end are executed. (Both foreach name (wordlist) and end must appear alone on separate lines.) The built-in command continue may be used to continue the loop prematurely and the built-in command break to terminate it prematurely. When this command is read from the terminal, the contents of the loop are read by prompting with ``?'' until end is typed before any statements in the loop are exe- cuted. glob wordlist Like echo but no ``\'' escapes are recognized and words are delimited by null characters in the output. Useful for pro- grams which wish to use the shell to apply filename expansion to a list of words. goto word Filename and command expansion is applied to the specified word to yield a string of the form label:. The shell rewinds its input as much as possible and searches for a line of the form label: possibly preceded by blanks or tabs. Execution continues after the specified line. history Displays the history event list. if (expr) command If the specified expression evaluates true, then the single command with arguments is executed. Variable substitution on command happens early, at the same time it does for the rest of the if command. command must be a simple command, not a pipeline, a command list, or a parenthesized command list. Input/output redirection occurs even if expr is false, and command is not executed. if (expr) then ... else if (expr2) then ... else ... endif If the specified expr is true then the commands before the first else are executed; else if expr2 is true then the com- mands after the second then and before the second else are executed, etc. Any number of else-if pairs are possible; only one endif is needed. The else part is likewise optional. (The words else and endif must appear at the beginning of input lines; the if (expr) then must appear alone on its input line or after an else.) logout Terminates a login shell. Use this if ignoreeof is set. nice nice +number nice command nice +number command The first form sets the nice for this shell to 4. By default, commands run under C-Shell have a ``nice value'' of 0. The second form sets the nice to the given number. The final two forms run command at priority 4 and number respec- tively. The super user may specify negative niceness by using ``nice -number ....'' The command is always executed in a subshell, and the restrictions placed on commands in simple if statements apply. nohup nohup command The first form can be used in shell scripts to cause hangups to be ignored for the remainder of the script. The second form causes the specified command to be run with hangups ignored. Unless the shell is running in the background, nohup has no effect. All processes running in the background with ``&'' are automatically nohuped. onintr onintr - onintr label Controls the action of the shell on interrupts. The first form restores the default action of the shell on interrupts which is to terminate shell scripts or to return to the ter- minal command input level. The second form, onintr -, causes all interrupts to be ignored. The final form causes the shell to execute a goto label when an interrupt is received or a child process terminates because it was interrupted. In any case, if the shell is running in the background, interrupts are ignored whether any form of onintr is present or not. rehash Causes the internal hash table of the contents of the direc- tories in the path variable to be recomputed. This is needed if new commands are added to directories in the path while you are logged in. repeat count command The specified command, which is subject to the same restric- tions as the command in the simple if statement above, is executed count times. I/O redirection occurs exactly once, even if count is 0. set set name set name=word set name[index]=word set name=(wordlist) The first form of the command shows the value of all shell variables. Variables which have other than a single word as value print as a parenthesized word list. The second form sets name to the null string. The third form sets name to the single word. The fourth form sets the indexth component of name to word; this component must already exist. The final form sets name to the list of words in wordlist. Com- mand and filename expansion is applied in all cases. These arguments may be repeated to set multiple values in a single set command. Note however, that variable expansion happens for all arguments before any setting occurs. setenv name value Sets the value of the environment variable name to be value, which must be a single string. Two useful environment vari- ables are TERM, the type of your terminal and SHELL, the shell you are using. shift shift variable In the first form, the members of argv are shifted to the left, discarding argv[1]. It is an error for argv not to be set or to have less than one word as a value. The second form performs the same function on the specified variable. source name The shell reads commands from name. Source commands may be nested, but if they are nested too deeply, the shell may run out of file descriptors. An error in a source at any level terminates all nested source commands, including the csh pro- cess from which source was called. If source is called from the login shell, it is logged out. Input during source com- mands is never placed on the history list. switch (string) case str1: ... breaksw ... default: ... breaksw endsw Command and filename substitution is applied to string; each case label is then successively matched against the result. Variable expansion is also applied to the case labels, so the file metacharacters ``*'', ``?'', and ``[...]'' can be used. If none of the labels match before a default label is found, then the execution begins after the default label. Each case label and the default label must appear at the beginning of a line. The command breaksw causes execution to continue after the endsw. Otherwise control may fall through case labels and default labels, as in C. If no label matches and there is no default, execution continues after the endsw. time time command With no argument, a summary of CPU time used by this shell and its children is printed. If arguments are given, the specified simple command is timed and a time summary as described under the time variable is printed. If necessary, an extra shell is created to print the time statistic when the command completes. command has the same restrictions as the simple if statement described above. umask umask value The file creation mask is displayed (no arguments) or set to the specified value (one argument). The mask is given in octal. Common values for the mask are 002 giving all access to the group and read and execute access to others, or 022 giving read and execute access to users in the group and all other users. unalias pattern All aliases whose names match the specified pattern are dis- carded. Thus, all aliases are removed by unalias *. It is not an error for nothing to be unaliased. unhash Use of the internal hash table to speed location of executed programs is disabled. unset pattern All variables whose names match the specified pattern are removed. Thus, all variables are removed by unset *; use this with care. It is not an error for nothing to be unset. wait All child processes are waited for. If the shell is interac- tive, then an interrupt can disrupt the wait, at which time the shell prints names and process numbers of all children known to be outstanding. while (expr) ... end While the specified expression evaluates nonzero, the com- mands between the while and the matching end are evaluated. break and continue may be used to terminate or continue the loop prematurely. (The while (expr) and end must appear alone on their input lines.) Prompting occurs here the first time through the loop as for the foreach statement if the input is a terminal. @ @ name = expr @ name[index] = expr The first form prints the values of all the shell variables. The second form sets the specified name to the value of expr. If the expression contains <, >, & or | then at least this part of the expression must be placed within ( ). The third form assigns the value of expr to the indexth argument of name. Both name and its indexth component must already exist. The operators *=, +=, etc. are available as in C. The space separating the name from the assignment operator is optional. Spaces are mandatory in separating components of expr which would otherwise be single words. The space between ``@'' and name is also mandatory. Special postfix ++ and -- operators increment and decrement name respectively, that is @ i++. Predefined variables The following variables have special meaning to the shell. Of these, argv, child, home, path, prompt, shell and status are always set by the shell. Except for child and status this setting occurs only at initiali- zation; these variables will not be modified unless done explicitly by the user. The shell copies the environment variable PATH into the variable path, and copies the value back into the environment whenever path is set. Thus it is not necessary to worry about its setting other than in the file .login since inferior csh processes will import the definition of path from the environment. argv Set to the arguments to the shell, it is from this vari- able that positional parameters are substituted, that is, $1 is replaced by argv[1], etc. argv[0] is not defined, but $0 is. cdpath Gives a list of alternate directories searched to find subdirectories in cd commands. child The process number of the last command forked with ``&''. This variable is unset when this process terminates. echo Set when the -x command line option is given. Causes each command and its arguments to be echoed just before it is executed. For nonbuilt-in commands all expansions occur before echoing. Built-in commands are echoed before com- mand and filename substitution, since these substitutions are then done selectively. histchars Can be assigned a two-character string. The first charac- ter is used as a history character in place of ``!'', the second character is used in place of the ``^'' substitu- tion mechanism. For example, set histchars=",;" will cause the history characters to be comma and semicolon. history Can be given a numeric value to control the size of the history list. Any command which has been referenced in this many events will not be discarded. A history that is too large may run the shell out of memory. The last exe- cuted command is always saved on the history list. home The home directory of the invoker, initialized from the environment. The filename expansion of ``~'' refers to this variable. ignoreeof If set, the shell ignores end-of-file from input devices that are terminals. This prevents a shell from acciden- tally being terminated by pressing <Ctrl>d. mail The files where the shell checks for mail. This check is executed after each command completion. The shell responds with, ``You have new mail'' if the file exists with an access time not greater than its modify time. If the first word of the value of mail is numeric, it specifies a different mail checking interval: in seconds, rather than the default, which is 10 minutes. If multiple mail files are specified, then the shell responds with ``New mail in name'', when there is mail in the file name. noclobber As described in the section ``Input/output'', restrictions are placed on output redirection to insure that files are not accidentally destroyed, and that >> redirections refer to existing files. noglob If set, filename expansion is inhibited. This is most useful in shell scripts which are not dealing with filenames, or after a list of filenames has been obtained and further expansions are not desirable. nonomatch If set, it is not an error for a filename expansion to not match any existing files; rather, the primitive pattern is returned. It is still an error for the primitive pattern to be malformed, that is, echo [ still gives an error. path Each word of the path variable specifies a directory in which commands are to be sought for execution. A null word specifies the current directory. If there is no path variable, then only full pathnames will execute. The usual search path is /bin, /usr/bin, and ., but this may vary from system to system. For the super-user, the default search path is /etc, /bin and /usr/bin. A shell which is given neither the -c nor the -t option will nor- mally hash the contents of the directories in the path variable after reading .cshrc, and each time the path variable is reset. If new commands are added to these directories while the shell is active, it may be necessary to give the rehash command, or the commands may not be found. prompt The string which is printed before reading each command from an interactive terminal input. If a ``!'' appears in the string, it will be replaced by the current event num- ber unless a preceding ``\'' is given. Default is ``%'', or ``#'' for the super user. shell The file in which the shell resides. This is used in forking shells to interpret files which have execute bits set, but which are not executable by the system. (See the description of ``Nonbuilt-in command execution'' below.) Initialized to the home of the shell. status The status returned by the last command. If it terminated abnormally, then 0200 is added to the status. Built-in commands which fail return exit status 1, otherwise these commands set status to 0. time Controls automatic timing of commands. If set, then any command which takes more than this many cpu seconds will cause a line to be sent to the screen displaying user time, system time, real time, and a utilization percentage which is the ratio of user plus system times to real time. verbose Set by the -v command line option, causes the words of each command to be printed after history substitution. Nonbuilt-in command execution When a command to be executed is found to not be a built-in csh command, the shell attempts to execute the command via exec(S). Each word in the variable path names a directory from which the shell will attempt to exe- cute the command. If it is given neither a -c nor a -t option, the shell will hash the names in these directories into an internal table so that it will only try an exec in a directory if there is a possibility that the command resides there. This greatly speeds command location when a large number of directories are present in the search path. If this mechanism has been turned off (via unhash), or if the shell was given a -c or -t argument, and for each directory component of path which does not begin with a ``/'', the shell concatenates each directory component of path with the given command name to form a pathname of a file which it then attempts to execute. Parenthesized commands are always executed in a subshell. Thus (cd; pwd); pwd prints the home directory but leaves you in the original directory, while cd; pwd moves you to the home directory. If the file has execute permissions but is not an executable binary to the system, then it is assumed to be a file containing shell commands and a new shell is spawned to read it. If there is an alias for shell then the words of the alias are prepended to the argument list to form the shell command. The first word of the alias should be the full pathname of the shell (for example, $shell). Note that this is a special, late occurring, case of alias substitution, and only allows words to be prepended to the argument list without modif- ication. Argument list processing If argument 0 to the shell is ``-'' then this is a login shell. The flag arguments are interpreted as follows: -c Commands are read from the (single) following argument which must be present. Any remaining arguments are placed in argv. -e The shell exits if any invoked command terminates abnormally or yields a nonzero exit status. -f The shell will start faster, because it will neither search for nor execute commands from the file .cshrc in the invoker's home direc- tory. -i The shell is interactive and prompts for its top-level input, even if it appears to not be a terminal. Shells are interactive without this option if their input and output are terminals. -n Commands are parsed, but not executed. This may aid in syntactic checking of shell scripts. -s Command input is taken from the standard input. -t A single line of input is read and executed. A ``\'' may be used to escape the newline at the end of this line and continue onto another line. -v Causes the verbose variable to be set, with the effect that command input is echoed after history substitution. -x Causes the echo variable to be set, so that commands are echoed immediately before execution. -V Causes the verbose variable to be set even before .cshrc is exe- cuted. -X Causes the echo variable to be set even before .cshrc is executed. After processing the flag arguments, if arguments remain but none of the -c, -i, -s, or -t options were given, the first argument is taken as the name of a file of commands to be executed. The shell opens this file, and saves its name for possible resubstitution by $0. On a typical sys- tem, most shell scripts are written for the standard shell (see sh(C)). The C shell will execute such a standard shell if the first character of the script is not a ``#'' (that is, if the script does not start with a comment). Remaining arguments initialize the variable argv. Signal handling The shell normally ignores quit signals. The interrupt and quit signals are ignored for an invoked command if the command is followed by ``&''; otherwise the signals have the values which the shell inherited from its parent. The shell's handling of interrupts can be controlled by onintr. By default, login shells catch the terminate signal; otherwise this sig- nal is passed on to children from the state in the shell's parent. In no case are interrupts allowed when a login shell is reading the file .logout. Files ~/.cshrc Read by each shell at the beginning of execution /etc/cshrc Systemwide default cshrc file for login C-shells ~/.login Read by login shell, after .cshrc at login ~/.logout Read by login shell, at logout /bin/sh Shell for scripts not starting with a ``#'' /tmp/sh* Temporary file for << /dev/null Source of empty file /etc/passwd Source of home directories for ~username Limitations Words can be no longer than 512 characters. The number of arguments to a command which involves filename expansion is limited to 1/6 the number of characters allowed in an argument list, which is 5120, less the charac- ters in the environment. The length of any argument of a command after filename expansion cannot exceed 159 characters. Also, command substitu- tions may substitute no more characters than are allowed in an argument list. To detect looping, the shell restricts the number of alias substitutions on a single line to 20. See also access(S), environ(M), exec(S), fork(S), pipe(S), signal(S), umask(S) and wait(S). User's Guide Credit This utility was developed at the University of California at Berkeley and is used with permission. Notes Built-in control structure commands like foreach and while cannot be used with |, & or ;. Commands within loops, prompted for by ``?'', are not placed in the his- tory list. It is not possible to use the colon (:) modifiers on the output of com- mand substitutions. The C-shell has many built-in commands with the same name and func- tionality as Bourne shell commands. However, the syntax of these C-shell and Bourne shell commands often differs. Two examples are the nice and echo commands. Be sure to use the correct syntax when working with these built-in C-shell commands. When a C-shell user logs in, the system reads and executes commands in /etc/cshrc before executing commands in the user's $HOME/.cshrc and $HOME/.login. You can, therefore, modify the default C-shell environment for all users on the system by editing /etc/cshrc. During intervals of heavy system load, pressing the delete key while at a C-shell prompt (%) may cause the shell to exit. If csh is the login shell, the user is logged out. csh attempts to import and export the PATH variable for use with regular shell scripts. This only works for simple cases, where the PATH contains no command characters. The || and && operators are reversed in this implementation.