csh

C Shell, a shell (command interpreter) with C-like syntax 

Command

SYNOPSIS

csh -l

csh [-befHinstvVxX] [-c [script]] [arg ...]

DESCRIPTION

The C Shell (csh) is a command language interpreter incorporating a history mechanism (see History Substitutions), job control facilities (see Jobs), interactive file name and user name completion (see File Name Completion ), and a C-like syntax. It is used both as an interactive login shell and a shell script command processor.

Options

When the first argument (argument 0) to the C Shell begins with the -, C Shell starts as a login shell. You can also specify a login shell by invoking csh with the -l option as the only argument.

csh also accepts the following options:

-b 

forces a "break" from option processing, causing any further command line arguments to be treated as non-option arguments. These arguments are not interpreted as C Shell options. This may be used to pass options to a shell script without confusion or possible subterfuge.

-c [script] 

reads commands from the specified script file. Any remaining arguments are placed in argv. If you omit script, the first available argument from the arg... list is used as script.

When the -c option is specified more than once, all but the last one on the command line are ignored. Corresponding script arguments are also ignored.

-e 

causes the C Shell to exit when any invoked command terminates abnormally or yields a non-zero exit status.

-f 

starts the C Shell faster by neither searching for nor executing commands from the $HOME/cshrc.csh file in your home directory.

-H 

starts the shell in hidden mode.

-i 

makes C Shell interactive and prompts for its top-level input, even if it appears not to be a terminal. Without this option, C Shell is only interactive when its input and output are terminals.

-l 

starts C Shell as a login shell. This is only applicable if -l is the only option specified.

-n 

parses commands but does not execute them. This aids in checking the syntax of shell scripts.

-s 

reads command input from the standard input.

-t 

reads and executes a single line of input. You can use a backslash (\) to escape the newline at the end of this line and continue onto another line.

-v 

sets the verbose variable, with the effect that command input is echoed after history substitution.

-V 

sets the verbose variable before $HOME/cshrc.csh is executed.

-x 

sets the echo variable, so that commands are echoed immediately before execution.

-X 

sets the echo variable before $HOME/cshrc.csh is executed.

After processing options 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 a command to be executed. The C Shell opens this file, and saves its name for possible resubstitution by $0. Remaining arguments are used to initialize the variable argv.

csh begins by executing commands from the file $ROOTDIR/etc/cshrc.csh and, if it is a login shell, $ROOTDIR/etc/login.csh. It then executes commands from $HOME/cshrc.csh in the home directory of the invoker, and, if it is a login shell, the file $HOME/login.csh in the same location.

Note:

If csh does not find a startup file with the Windows-style name, it searches for a file with the equivalent UNIX-style name (for example .cshrc instead of cshrc.csh).

In the normal case, C Shell begins reading commands from the terminal, prompting with %. Processing of arguments and the use of the C Shell to process files containing command scripts are described later.

The C 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 parsed. Finally each command in the current line is executed.

When a login shell terminates it executes commands from the files $ROOTDIR/etc/logout.csh and $HOME/logout.csh.

Lexical Structure

The C Shell splits input lines into words at blanks and tabs with the following exceptions. The following characters 

&      |      ;      <      >      (      )

form separate words. If doubled in &&, ||, <<, or >>, these pairs form single words. To enter these characters as normal characters with no special meaning, precede them with a backslash (\). A newline preceded by a backslash (\) is equivalent to a blank.

Strings enclosed in matched pairs of back quotes (`), single quotes (that is, apostrophes) ('), or double quotes (") form parts of a word; metacharacters in these strings, including blanks and tabs, do not form separate words. These quotations have semantics to be described later. Within pairs of ' or " characters, a newline preceded by a backslash (\) gives a true newline character.

When the C Shell's input is not a terminal, the # character introduces a comment that continues to the end of the input line. It is prevented this special meaning when preceded by \ and in quotations using ', `, and ".

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 commands separated by | characters forms a pipeline. The output of each command in a pipeline is connected to the input of the next. Sequences of pipelines may be separated by semicolons (;), and are executed sequentially. A sequence of pipelines may be executed without immediately waiting for it to terminate by following it with an &.

You may enclose any of the above in parentheses (( ))to form a simple command (that may be a component of a pipeline or similar construct). It is also possible to separate pipelines with || or && showing, as in the C language, that the second command is to be executed only if the first fails or succeeds, respectively (see Expressions).

Jobs

The C Shell associates a job with each pipeline. It keeps a table of current jobs, printed by its jobs command, and assigns them small integer numbers. When a job is started asynchronously with &', csh displays a line that looks like: 

[1] 1234

showing that the job that was started asynchronously was job number 1 and had one (top-level) process, whose process id was 1234.

A job being run in the background stops if it tries to read from the terminal.

There are several ways to refer to jobs in the C Shell. The % character introduces a job name. If you want to refer to job number 1, you can name it as %1. For example, if you have no jobs running in the background 

sleep 100 &
kill %1

terminates the sleep command. Jobs can also be named by prefixes of the string typed in to start them, if these prefixes are unambiguous. For example, 

sleep 100 &
kill %sl

terminates the sleep command, if there are no other jobs beginning with sl. It is also possible to say %?string which specifies a job whose text contains string, if there is only one such job.

The C Shell maintains a notion of the current and previous jobs. In output about jobs, the current job is marked with a + and the previous job with a -. The abbreviation %+ refers to the current job and %- refers to the previous job. For close analogy with the syntax of the C Shell's history mechanism (described later in this reference page), %% is also a synonym for the current job.

Status Reporting

This C Shell learns as soon as possible whenever a process changes state. It informs you whenever a job becomes blocked so that no further progress is possible. This notification only occurs when the shell next displays its prompt. This is done so that it does not otherwise disturb your work.

File Name Completion

When the file name completion feature is enabled by setting the filec shell variable (see the description of the C Shell's set command later in this reference page), csh interactively completes file names and user names from unique prefixes, when they are input from the terminal followed by the escape character (the ESC key, or CTRL-[). For example, if the current directory looks like 

DSC.OLD    bin         cmd         lib         xmpl.c
DSC.NEW    chaosnet    cmtest      mail        xmpl.o
bench      class       dev         mbox        xmpl.out

and the input is 

vi ch<escape>

csh completes the prefix ch to the only matching file name chaosnet, changing the input line to 

vi chaosnet

However, given 

vi D<escape>

csh only expands the input to 

DSC.

and sounds the terminal bell to indicate that the expansion is incomplete, since there are two file names matching the prefix D.

If a partial file name is followed by the end-of-file character (usually CTRL-Z then, instead of completing the name, csh lists all file names matching the prefix. For example, the input 

vi D<^Z>

lists all files beginning with D: 

DSC.NEW      DSC.OLD

while the input line remains unchanged.

The same system of escape and end-of-file can also be used to expand partial user names, if the word to be completed (or listed) begins with the character ~. For example, typing 

cd ~admin<escape>

may produce the expansion 

cd ~administrator

The use of the terminal bell to signal errors or multiple matches can be inhibited by setting the variable nobeep.

Normally, all files in the particular directory are candidates for name completion. Files with certain suffixes can be excluded from consideration by setting the fignore variable to the list of suffixes to be ignored. Thus, if fignore is set by the command 

set fignore = (.o .out)

then typing 

vi x<escape>

results in completion to 

vi xmpl.c

ignoring the files xmpl.o and xmpl.out. However, if the only completion possible requires not ignoring these suffixes, then they are not ignored. In addition, fignore does not affect the listing of file names by CTRL-Z. All files are listed regardless of their suffixes. If the DUALCASE variable is set, case is considered when completing file names; otherwise, case is ignored.

Substitutions

The following sections describe the various transformations the C Shell performs on the input in the order they occur in.

History Substitutions

History substitutions place words from previous command input as portions of new commands, making it easy to repeat commands, repeat arguments of a previous command in the current command, or fix spelling mistakes in the previous command with little typing and a high degree of confidence. History substitutions begin with the character ! and may begin anywhere in the input stream (as long as they are not nested). This ! may be preceded by a backslash (\) to prevent its special meaning; for convenience, ! is passed unchanged when it is followed by a blank, tab, newline, =, or (. (History substitutions also occur when an input line begins with ^. This special abbreviation is described later in this reference page.) Any input line that contains history substitution is echoed on the terminal before it is executed as it could have been typed without history substitution.

Commands input from the terminal that consist of one or more words are saved on the history list. The history substitutions reintroduce sequences of words from these saved commands into the input stream. The size of the history list is controlled by the history variable; the previous command is always retained, regardless of the value of the history variable. Commands are numbered sequentially from 1.

For example, consider the following output from the C Shell's history command: 

\09  mapimail michael
10  vi write.c
11  cat oldwrite.c
12  diff *write.c

The commands are shown with their event numbers. It is not usually necessary to use event numbers, but the current event number can be made part of the prompt by placing an ! in the prompt string.

With the current event 13, you can refer to previous events by event number !11, relatively as in !-2 (referring to the same event), by a prefix of a command word as in !d for event 12 or !mapi for event 9, or by a string contained in a word in the command as in !?mic? also referring to event 9. These forms, without further change, simply reintroduce the words of the specified events, each separated by a single blank. As a special case, !! refers to the previous command; thus !! alone is a redo.

To select words from an event we can follow the event specification by a : 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 designators are: 

0	the first (command) word
n	the nth argument
^	the first argument, that is, 1
$	the last argument
%	the word matched by an immediately preceding ?s? search
x-y	range of words
-y	abbreviation for 0-y
*	abbreviation for ^-$, or nothing if only 1 word in event
x*	abbreviation for 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 can be placed a sequence of modifiers, each preceded by a :. The following modifiers are defined: 

h	removes a trailing path name component, leaving the head.
r	removes a trailing .xxx component, leaving the root name.
e	removes all but the extension .xxx part.
s/l/r/	substitutes l for r
t	removes all leading path name components, leaving the tail.
&	repeats the previous substitution.
g	applies the change once on each word, prefixing the above, for example, g&.
a	applies the change as many times as possible on a single word, prefixing the above
	(can be used together with g to apply a substitution globally).
p	prints the new command line but does not execute it.
q	quotes the substituted words, preventing further substitutions.
x	is like q, but breaks into words at blanks, tabs and newlines.

Unless preceded by the g modifier, the change is applied only to the first modifiable word. With substitutions, it is an error for no word to be applicable.

The left hand side of substitutions are not regular expressions in the sense of the editors, but instead strings. Any character may be used as the delimiter in place of the slash (/); a backslash (\) quotes the delimiter in the l and r strings. The character & in the right hand side is replaced by the text from the left. A \ also quotes &. A null left side (//) uses the previous string either from an l or from a contextual scan string s in !?s\?. The trailing delimiter 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, !$. Here, the reference is to the previous command unless a previous history reference occurred on the same line in which case this form repeats the previous reference. 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, you might do !{l}a to do ls -ld ~paula, while !la would look for a command starting with la.

Quoting Strings

The quotation of strings by ' and " can be used to prevent all or some of the remaining substitutions. Strings enclosed in ' are prevented any further interpretation. Strings enclosed in " may be expanded as described below.

In both cases the resulting text becomes (all or part of) a single word; only in one special case (see Command Substitution) does a " quoted string yield parts of more than one word; ' quoted strings never do.

Alias Substitution

The C Shell maintains a list of aliases that can be established, displayed and modified by the C Shell's 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 that is the alias for that command is reread with the history mechanism available 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 /winnt

maps to 

ls -l /winnt

the argument list here being undisturbed.

If an alias is found, the word transformation of the input text is performed and the aliasing process begins again on the reformed input line. Looping is prevented if the first word of the new text is the same as the old by flagging it to prevent further aliasing. Other loops are detected and cause an error.

Note that the mechanism allows aliases to introduce parser metasyntax. For example, 

alias ms 'man  \!* | manstrip'

creates a command that displays a version of the specified reference pages stripped of backspace characters and ANSI color escape sequences.

Variable Substitution

The C Shell maintains a set of variables, each of which has as value a list of zero or more words. Some of these variables are set by the shell or referred to by it. For instance, the argv variable is an image of the C 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 C Shell's set and unset commands. Of the variables referred to by the C Shell, a number are toggles; that is, the shell does not care what their value is, only whether they are set or not. For instance, the verbose variable is a toggle that causes command input to be echoed. The setting of this variable results from the -v command line option.

Other operations treat variables numerically. The @ command permits numeric calculations to be performed and the result assigned to a variable. Variable values are, however, 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 additional words of multiword values are ignored.

After the input line is aliased and parsed, and before each command is executed, variable substitution is performed keyed by $ characters. This expansion can be prevented by preceding the $ with a \ except within double quotes (") where it always occurs, and within single quotes (') where it never occurs. Strings quoted by ` are interpreted later (see Command Substitution) so $ substitution does not occur there until later, if at all. $ is passed unchanged if followed by a blank, tab, or end-of-line.

Input/output redirections are recognized before variable expansion, and are variable expanded separately. Otherwise, the command name and entire argument list are expanded together. It is thus possible for the first (command) word (to this point) 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 quotes (") or given the :q modifier, the results of variable substitution may eventually be command and file name substituted. Within double quotes ("), a variable whose value consists of multiple words expands to (a portion of) a single word, with the words of the variables 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 file name substitution.

The following metasequences are provided for introducing variable values into the C Shell input. Except as noted, it is an error to reference a variable that 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 that would otherwise be part of it. Shell variables have names consisting of up to 20 letters and digits starting with a letter. The underscore character is considered a letter. When name is not a shell variable, but is set in the environment, that value is returned (but : modifiers and the other forms given later are not available here).

$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 variables value is numbered 1. If the first number of a range is omitted it defaults to 1. If the last number 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 $argv[selector].

$0 

Substitutes the name of the file the command input is being read from. An error occurs if the name is not known.

$number 
${number} 

Is equivalent to $argv[number].

$* 

Is equivalent to $argv[*]. The modifiers :e, :h, :t, :r, :q, and :x may be applied to the substitutions above as may :gh, :gt, and :gr. When braces ({ }) appear in the command form, the modifiers must appear within the braces. The current implementation of csh allows only one : modifier on each $ expansion.

The following substitutions may not be modified with : modifiers.

$?name 
${?name} 

Substitutes the string 1 if the variable name is set, 0 if it is not.

$?0 

Substitutes 1 if the current input file name is known, 0 if it is not.

$$ 

Substitutes the (decimal) process number of the (parent) shell.

$! 

Substitutes the (decimal) process number of the last background process started by this shell.

$< 

Substitutes a line from the standard input, with no further interpretation. It can be used to read from the keyboard in a shell script.

Command and File Name Substitution

The remaining substitutions, command and file name substitution, are applied selectively to the arguments of built-in commands. In this case, selectively means that portions of expressions that are not evaluated are not subjected to these expansions. For commands that are not internal to the C Shell, the command name is substituted 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 shown by a command enclosed in `. The output from such a command is normally broken into separate words at blanks, tabs and newlines, with null words being discarded; this text then replaces the original string. Within double quotes ("), 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 thus possible for a command substitution to yield only part of a word, even if the command outputs a complete line.

File Name Substitution

When a word contains any of the characters *, ?, [, or { or begins with the character ~, that word is a candidate for file name substitution, also known as globbing. This word is then regarded as a pattern, and replaced with an alphabetically sorted list of file names that match the pattern. In a list of words specifying file name substitution it is an error for no pattern to match an existing file name, but it is not required for each pattern to match. Only the metacharacters *, ?, and [ imply pattern matching, the characters ~ and { being more akin to abbreviations.

In matching file names, the character . at the beginning of a file name or immediately following a /, as well as the character / must be matched explicitly. The character * matches any string of characters, including the null string. The character ? matches any single character. The sequence ... matches any one of the characters enclosed. Within ..., a pair of characters separated by - matches any character lexically between the two (inclusive).

The character ~ at the beginning of a file name refers to home directories. Standing alone, that is, ~ it expands to the invoker's home directory as reflected in the value of the variable home. When followed by a name consisting of letters, digits and - characters, the shell searches for a user with that name and substitutes their home directory; thus ~ken might expand to c:/users/ken and ~ken/chmach to c:/users/ken/chmach. If the character ~ is followed by a character other than a letter or / or does not appear at the beginning of a word, it is left undisturbed.

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. This construct may be nested. Thus, ~source/s1/{oldls,ls}.c expands to /usr/source/s1/oldls.c /usr/source/s1/ls.c without chance of error if the home directory for source is /usr/source. Similarly ../{memo,*box} might expand to ../memo ../box ../mbox. (Note that memo was not sorted with the results of the match to *box.) As a special case {, }, and {} are passed undisturbed.

Note:

When calling other commands from csh, be careful to escape any wildcards in the command line. For example, you must type the following in csh: 

find / -name \*.bat

Input/Output

The standard input and the standard output of a command may be redirected with the following syntax:

< filename 

Opens file filename (after filename is variable, command and file name expanded) as the standard input.

<< word 

Reads the C Shell input up to a line that is identical to word. word is not subjected to variable, file name or command substitution, and each input line is compared to word before any substitutions are done on the input line. Unless a quoting \, ", ', or ` appears in word, variable and command substitution is performed on the intervening lines, allowing \ to quote $, \ and `. Commands that are substituted have all blanks, tabs, and newlines preserved, except for the final newline which is dropped. The resultant text is placed in an anonymous temporary file that is given to the command as its standard input.

> filename 
>! filename 
>& filename 
>&! filename 

Uses filename as the standard output. If the file does not exist then it is created; if the file exists, it is truncated; its previous contents are lost.

If the variable noclobber is set, then the file must not exist or be a character special file (for example, a terminal or nul) or an error results. This helps prevent accidental destruction of files. Here, the ! forms can be used to suppress this check.

The forms involving & route the standard error output into the specified file as well as the standard output. filename is expanded in the same way as < input file names are.

>> filename 
>>& filename 
>>! filename 
>>&! filename 

Uses filename as the standard output; like > but places output 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, it is similar to >.

A command receives the environment where the C Shell was invoked as modified by the input-output parameters and the presence of the command in a pipeline. Thus, unlike some previous shells, commands run from a file of C Shell commands have no access to the text of the commands by default; instead 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. Note that the default standard input for a command run detached is not modified to be the empty file nul; instead the standard input remains as the original standard input of the shell. If this is a terminal and if the process attempts to read from the terminal, then the process blocks and the user is notified (see Jobs earlier in this reference page).

The standard error output may be directed through a pipe with the standard output. Simply use the form |& instead of just |.

Expressions

Several of the built-in commands (to be described later) take expressions, where the operators are similar to those of C, with the same precedence. These expressions appear in the @, exit, if, and while commands. The following operators are available: 

||   &&  |    ^    &    ==   !=   =~   !~   <=   >=
<    >   <<   >>   +    -    *    /    %    !    ~    (    )

Here the precedence increases to the right. Each of the following lines lists operators that have the same level of precedence: 

==    !=   =~   !~
<=    >=   <    >
<<    >>
+     -
*     /    %

The ==, !=, =~, and !~ operators compare their arguments as strings; all others operate on numbers. The operators =~ and !~ operators are like != and == except the right hand side is a pattern (containing, for example, *s, ?s and instances of [...]) that the left hand operand is matched against. This reduces the need for use of the switch statement in shell scripts when all that is really needed is pattern matching.

Strings that 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. It is important to note that no two components of an expression can appear in the same word; except when adjacent to components of expressions that are syntactically significant to the parser (&, |, <, >, (, and )), they should be surrounded by spaces.

Also available in expressions as primitive operands are command executions 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

The specified name is command and file name expanded and then 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 an expression and the variable status examined.

Control Flow

The C Shell contains several commands that can be used to regulate the flow of control in command files (shell scripts) and (in limited but useful ways) from terminal input. These commands all operate by forcing the shell to reread or skip in its input and, because of the implementation, restrict the placement of some of the commands.

The foreach, switch, and while statements, as well as the if-then-else form of the if statement require that the major keywords appear in a single simple command on an input line as shown later.

If the C 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 accomplish the rereading implied by the loop. (To the extent that this allows, a backward goto succeeds on non-seekable inputs.)

Built-in Commands

Built-in commands are executed within the C Shell. If a built-in command occurs as any component of a pipeline except the last, it is executed 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 command and file name substituted. name cannot be alias or unalias.

This is an internal C Shell command and should not be confused with the alias command built into the MKS KornShell.

alloc 

Shows the amount of dynamic memory acquired, broken down into used and free memory.

bg 

Is not supported.

break 

Causes execution to resume after the end of the nearest enclosing foreach or while. The remaining commands on the current line are executed. Multi-level breaks are thus possible by writing them all on one line.

This is an internal C Shell command and should not be confused with the break command built into the MKS KornShell.

breaksw 

Causes a break from a switch, resuming after the endsw.

case label: 

A label in a switch statement as discussed later.

cd 
cd name 
chdir 
chdir name 

Changes the shell's working directory to directory name. If no argument is given then change to the home directory of the user. If name is not found as a subdirectory of the current directory (and does not begin with x:/, //, ./, or ../), 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.

This is an internal C Shell command and should not be confused with the cd command built into the MKS KornShell.

continue 

Continues execution of the nearest enclosing while or foreach. The rest of the commands on the current line are executed.

This is an internal C Shell command and should not be confused with the cd command built into the MKS KornShell.

default : 

Labels the default case in a switch statement. The default should come after all case labels.

dirs 

Prints the directory stack; the top of the stack is at the left, the first directory in the stack being the current directory.

This is an internal C Shell command and should not be confused with the PTC MKS Toolkit dirs command.

echo wordlist 
echo -n wordlist 

The specified words are written to the C Shell's standard output, separated by spaces, and terminated with a newline unless the -n option is specified.

This is an internal C Shell command and should not be confused with the echo command built into the MKS KornShell.

else 
end 
endif 
endsw 

See the description of the foreach, if, switch, and while statements later in this reference page.

eval arg ... 

The arguments are read as input to the C Shell and the resulting command(s) are executed in the context of the current shell. This is usually used to execute commands generated as the result of command or variable substitution, since parsing occurs before these substitutions.

This is an internal C Shell command and should not be confused with the eval command built into the MKS KornShell.

exec command 

The specified command is executed in place of the current shell.

This is an internal C Shell command and should not be confused with the exec command built into the MKS KornShell.

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).

This is an internal C Shell command and should not be confused with the exit command built into the MKS KornShell.

fg 

Is not supported.

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 command are executed. (Both foreach and end must appear alone on separate lines.) The built-in C Shell command continue may be used to continue the loop prematurely and the built-in C Shell command break may be used to terminate it prematurely. When this command is read from the terminal, the loop is read once prompting with ? before any statements in the loop are executed. If you make a mistake typing in a loop at the terminal you can rub it out.

glob wordlist 

Is like the echo command but no \ escapes are recognized and words are delimited by null characters in the output. This is useful for programs that want to use the shell to file name expand a list of words.

goto word 

The specified word is file name and command expanded 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.

hashstat 

Prints a statistics line showing how effective the internal hash table has been at locating commands (and avoiding execs). An exec is attempted for each component of the path where the hash function indicates a possible hit, and in each component that does not begin with x:/ or //.

history 
history n 
history -r n 
history -h n 

Displays the history event list; if n is given only the n most recent events are printed. The -r option reverses the order of printout to be most recent first instead of oldest first. The -h option causes the history list to be printed without leading numbers. This format produces files suitable for sourcing using the -h option to the source command.

This is an internal C Shell command and should not be confused with the history alias for fc built into the MKS KornShell.

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, that is, when command is not executed (this is a bug).

This is an internal C Shell command and should not be confused with the if command built into the MKS KornShell.

if (expr) then 
... 
else if(expr2) then 
... 
else 
... 
endif 

If the specified expr is true then the commands up to the first else are executed; otherwise if expr2 is true, the commands up to the second else are executed, and so on. 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 must appear alone on its input line or after an else.)

This is an internal C Shell command and should not be confused with the if command built into the MKS KornShell.

jobs 
jobs -l 

Lists the active jobs; the -l option lists process IDs in addition to the normal information.

This is an internal C Shell command and should not be confused with the jobs command built into the MKS KornShell.

kill %job 
kill pid 
kill -l sig pid 
kill -l 

Sends either the TERM (terminate) signal or the specified signal to the specified jobs or processes. Signals are either given by number or by names . The signal names are listed by kill -l. There is no default, just saying kill does not send a signal to the current job.

This is an internal C Shell command and should not be confused with the kill command built into the MKS KornShell.

limit 

Is not supported.

login 

Is not supported.

logout 

Terminates a login shell. This is especially useful if ignoreeof or filec is set.

nice 

Is not supported.

nohup 

Is not supported.

notify 
notify% %job ... 

Is accepted by this version of csh, but effectively does nothing. It is included for compatibility with other versions of csh.

onintr 
onintr - 
onintr label 

Controls the action of the C Shell on interrupts. The first form restores the default action of the shell on interrupts that are to terminate shell scripts or to return to the terminal command input level. The second form onintr - causes all interrupts to be ignored. The final form causes the C 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 detached and interrupts are being ignored, all forms of onintr have no meaning and interrupts continue to be ignored by the shell and all invoked commands. Finally, onintr statements are ignored in the system startup files where interrupts are disabled ($ROOTDIR/etc/cshrc.csh and $ROOTDIR/etc/login.csh).

popd 
popd +n 

Pops the directory stack, returning to the new top directory. With an argument +n, it discards the nth entry in the stack. The members of the directory stack are numbered from the top starting at 0.

This is an internal C Shell command and should not be confused with the PTC MKS Toolkit popd command.

pushd 
pushd name 
pushd +n 

With no arguments, pushd exchanges the top two elements of the directory stack. Given a name argument, pushd changes to the new directory (in the same way as cd) and pushes the old current working directory onto the directory stack. With a numeric argument, pushd rotates the nth argument of the directory stack around to be the top element and changes to it. The members of the directory stack are numbered from the top starting at 0.

This is an internal C Shell command and should not be confused with the PTC MKS Toolkit pushd command.

rehash 

Causes the internal hash table of the contents of the directories in the path variable to be recomputed. This is needed if new commands are added to directories in the path while you are using csh.

repeat count command 

The specified command, which is subject to the same restrictions as the command in the one line if statement earlier, is executed count times. Input and output redirections occur 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 that have other than a single word as their 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. The value is always command and file name expanded.

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.

This is an internal C Shell command and should not be confused with the set command built into the MKS KornShell.

setenv 
setenv name 
setenv name value 

The first form lists all the current environment variables. The second form sets the value of the environment variable name to an empty string. The last form sets the value of the environment variable name to be value, a single string.

shift 
shift variable 

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 value. The second form performs the same function on the specified variable.

This is an internal C Shell command and should not be confused with the shift command built into the MKS KornShell.

source name 
source -h name 

The C Shell reads commands from name. source commands may be nested; if they are nested too deeply the shell may run out of file descriptors. An error in a source command at any level terminates all nested source commands. Normally input during source commands is not placed on the history list; the -h option causes the commands to be placed on the history list without being executed.

stop 
stop %job ... 

Is not supported.

suspend 

Causes the shell to stop in its tracks.

switch (string) 
case str1 
... 
breaksw 
... 
breaksw 
... 
endsw 

Each case label is successively matched against the specified string after string is command and file name expanded. The file metacharacters *, ?, and [...] may be used in the case labels, which are variable expanded. If none of the labels match before the `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 the default label as in C. If no label matches and there is no default, execution continues after the endsw.

case is an internal C Shell command and should not be confused with the case command built into the MKS KornShell.

time 
time command 

With no argument, a summary of 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.

This is an internal C Shell command and should not be confused with the time command built into the MKS KornShell.

umask 
umask value 

The file creation mask is displayed (first form) or set to the specified value (second form). 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 all access except write access for users in the group or others.

This is an internal C Shell command and should not be confused with the umask command built into the MKS KornShell.

unalias pattern 

All aliases whose names match the specified pattern are discarded. Thus all aliases are removed by unalias *. It is not an error for nothing to be unaliased.

This is an internal C Shell command and should not be confused with the unalias command built into the MKS KornShell.

unhash 

Disables the use of the internal hash table to speed location of executed programs.

unlimit 

Is not supported.

unset pattern 

All variables whose names match the specified pattern are removed. Thus all variables are removed by unset *; this has noticeably distasteful side-effects. It is not an error for nothing to be unset.

This is an internal C Shell command and should not be confused with the unset command built into the MKS KornShell.

unsetenv pattern 

Removes all variables whose name match the specified pattern from the environment. See also the setenv command earlier in this reference page.

wait 

Waits for all background jobs. If the shell is interactive, then an interrupt can disrupt the wait. After the interrupt, the shell prints names and job numbers of all jobs known to be outstanding.

This is an internal C Shell command and should not be confused with the wait command built into the MKS KornShell.

which command 

Displays the resolved command that is executed by the shell.

This is an internal C Shell command and should not be confused with the which command built into the MKS KornShell.

while (expr) 
... 
end 

While the specified expression evaluates non-zero, the commands between the while and the matching end are evaluated. break and continue may be used to terminate or continue the loop prematurely. (The while 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.

This is an internal C Shell command and should not be confused with the while command built into the MKS KornShell.

%job 

Is not supported.

%job & 

Is not supported.

@ 
@ 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 *=, +=, and so forth are available as in C. The space separating the name from the assignment operator is optional. Spaces are, however, mandatory in separating components of expr that would otherwise be single words.

Special postfix ++ and -- operators increment and decrement name respectively. For example 

@  i++

increments the variable i.

Pre-defined Variables

The following variables have special meaning to the C Shell. Of these, argv, csh_version, cwd, home, path, prompt, ROOTDIR, shell, status, COMSPEC, and TMPDIR are always set by the shell. Except for cwd and status, this setting occurs only at initialization; these variables are then not modified unless done explicitly by the user.

The shell copies version information into the variable csh_version.

To set the variable TMPDIR, the C Shell works its way through the following environment variables in the order listed until it finds one that is set. It copies that environment variable to TMPDIR. 

TMPDIR
TEMP
TMP
ROOTDIR

The C Shell copies the environment variable CSHPATHEXT into the variable CSHPATHEXT, PATHEXT into the variable PATHEXT, HASHBANG into HASHBANG, DUALCASE into DUALCASE, ROOTDIR into ROOTDIR, COMSPEC into COMSPEC, TERM into term, and HOME into home. The environment variable PATH is likewise handled; it is not necessary to worry about its setting other than in the file $HOME/cshrc.csh as csh processes import the definition of path from the environment, and re-export it if you then change it.

argv 

Is set to the arguments to the shell. It is from this variable that positional parameters are substituted, that is, $1 is replaced by $argv[1], and so forth.

cdpath 

Gives a list of alternative directories searched to find subdirectories in chdir commands.

cwd 

The full path name of the current directory.

DUALCASE 

When set, file name comparisons (for example, in globbing, or file name expansion, and file name completion) are case-sensitive. When not set, case is ignored in file name comparisons.

echo 

Is set when the -x command line option is given. It causes each command and its arguments to be echoed just before it is executed. For non-built-in commands all expansions occur before echoing. Built-in commands are echoed before command and file name substitution, since these substitutions are then done selectively.

filec 

Enables file name completion.

HASHBANG 

enables or disables the #! feature of the C Shell. If this variable is set to a non-zero value, the feature is enabled; otherwise, it is disabled. When this feature is enabled and the first line of a C Shell script file is of the form: 

#![command] [arguments]

command is executed with a command line consisting of arguments followed by the path name of the script file. If command has a UNIX-style path name (starts with a forward slash and has no file name extension) and cannot be found, then, for portability reasons, the shell attempts a path search on the basename of command. For example, suppose the file script has the first line 

#!/usr/bin/perl

Typing script on the C Shell command line executes the script using the perl command.

Note:

When the TK_HASHBANG_DO_NOT_SEARCH_PATH environment variable is set to a non-zero value and command cannot be found, the shell does not attempt a path search on the basename of command.

histchars 

Can be given a string value to change the characters used in history substitution. The first character of its value is used as the history substitution character, replacing the default character !. The second character of its value replaces the character ^ in quick substitutions.

histfile 

Can be set to the path name of the file where the history is going to be saved/restored.

history 

Can be given a numeric value to control the size of the history list. Any command that has been referenced in this many events is not discarded. Assigning too large of a value to history can cause the C Shell to run out of memory. The last executed command is always saved on the history list.

home 

Is the home directory of the invoker, initialized from the environment. The file name expansion of ~ refers to this variable.

ignoreeof 

If set, the C Shell ignores end-of-file from input devices that are terminals. This prevents shells from accidentally being killed by control-Z's.

mail 

Is the files where the C Shell checks for mail. This checking is done after each command completion that results in a prompt, if a specified interval has elapsed. The shell says 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, than the default of 10 minutes.

If multiple mail files are specified, then the C Shell says New mail in name. when there is mail in the name file.

noclobber 

As described in the section on Input/Output, restrictions are placed on output redirection to make sure that files are not accidentally destroyed, and that >> redirections refer to existing files.

noglob 

If set, file name expansion is inhibited. This inhibition is most useful in shell scripts that are not dealing with file names, or after a list of file names has been obtained and further expansions are not desirable.

nonomatch 

If set, it is not an error for a file name expansion to not match any existing files; instead the primitive pattern is returned. It is still an error for the primitive pattern to be malformed, that is, echo [ still gives an error.

notify 

Is accepted by this version of csh, but effectively does nothing. It is included for compatibility with other versions of csh.

path 

Each word of the path variable specifies a directory where commands are to be sought for execution. A null word specifies the current directory. If there is no path variable then only full path names execute. The default search path is usually: 

/mksnt;c:/winnt;c:/winnt/system32

A C Shell that is given neither the -c nor the -t option normally hashes the contents of the directories in the path variable after reading $HOME/cshrc.csh, 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 do a rehash so that these new commands can be found.

PATHEXT 

contains a list of file extensions (separated by semicolons) for executable commands. Matching files with these extensions are searched for when the exact command name is not found. As the shell searches each directory in the search path, it appends each of the extensions in the list, in turn, to the command name and if it matches a file name in that directory, that file is executed as though it had that extension.

By default, PATHEXT, has the value of 10/2016/2019/11/2022/2025's PATHEXT variable with .com;.exe;.bat;.sh;.ksh;.csh;.sed;.awk;.pl appended (omitting any extensions already represented in PATHEXT).

prompt 

Is the string that is printed before each command is read from an interactive terminal input. If a ! appears in the string it is replaced by the current event number unless a preceding \ is given. Default is %, or # for the super-user.

savehist 

Is given a numeric value to control the number of entries of the history list that are saved in ~/history.csh when the user logs out. Any command that has been referenced in this many events is saved. During start up the shell sources ~/history.csh into the history list enabling history to be saved across logins. Large values of savehist may slow down the shell during start up. If savehist is set to an empty string, the shell uses the value of history.

shell 

Is the file where the shell resides. Initialized to the (system-dependent) home of the shell.

status 

The status returned by the last command. Built-in commands that fail return exit status 1; all other built-in commands set status to 0.

time 

Controls automatic timing of commands. If set, any command taking more than this many CPU seconds causes a line giving user time to be printed when it terminates.

TK_CSH_DO_NOT_HASH_PATH 

When set, csh does not hash the path.

TK_CSH_LOGIN_START_DIRECTORY_IS_HOME 

When set, specifies that the command csh -l always starts in the directory specified by the HOME environment variable. when not set, csh -l starts in the current directory.

Normally, MKS Toolkit shortcuts start in the directory specified by the USERPROFILE environment variable. By default, the USERPROFILE and HOME environment variables have the same value and thus, the MKS Toolkit csh shortcut (which is defined as as csh -l) starts in the HOME directory. However, some users have the USERPROFILE environment variable set to a different value than the HOME environment variable but expect the csh shortcut to start in the HOME directory. By setting the TK_CSH_LOGIN_START_DIRECTORY_IS_HOME environment variable, these users can get the expected behavior.

TK_CSH_SEARCH_PATH_FOR_CMDLINE_SCRIPT 

when set, csh checks to see if a script specified on the command line is in the directory contained in the PWD environment variable and if it is not, it searches for the script in the directories named in the PATH environment variable. If the name of the specified script does not end in .csh, csh searches for the script in the directories specified by the PWD and PATH environment variables.

TK_CMDSUB_FORMAT 

Contains the format to be used for the output from command substitution in MKS C Shell (the `command_line` structure). The value must be one of those listed in the File Character Formats section of the unicode reference page.

When TK_CMDSUB_FORMAT is not set, the value of the TK_STDIO_DEFAULT_INPUT_FORMAT environment variable is used as the default format.

When TK_CMDSUB_FORMAT and TK_STDIO_DEFAULT_INPUT_FORMAT are both unset, either ASCII_OEM or ASCII_ANSI is used as the default format, as dictated by the current code page. This provides compatibility with older versions of MKS Toolkit.

TK_FILENAME_COMPLETION 

when set to a valid value, this variable overrides the DUALCASE environment variable with respect to file name completion. Vaild values are case sensitive and case insensitive.

TK_HASHBANG_DO_NOT_SEARCH_PATH 

When set to a non-zero value, and the command in: 

#![command] [arguments]

cannot be found, the shell does not attempt a path search on the basename of command.

TK_HEREDOC_FORMAT 

Contains the format to be used for here documents in MKS C Shell. The value must be one of those listed in the File Character Formats section above.

When TK_HEREDOC_FORMAT and TK_STDIO_DEFAULT_OUTPUT_FORMAT are both unset, here documents are assumed to use ASCII_OEM characters. This provides compatibility with older versions of MKS Toolkit.

When TK_STDIO_DEFAULT_OUTPUT_FORMAT is set to a Unicode/UTF-8 format and you are feeding a here document to to a non-MKS Toolkit utility that won't understand its format, you should set TK_HEREDOC_FORMAT to ASCII_OEM and export it.

When TK_HEREDOC_FORMAT is unset or TK_STDIO_DEFAULT_OUTPUT_FORMAT is set to an ASCII format and your here document contains non-ASCII (OEM) characters, you should set TK_HEREDOC_FORMAT to UTF-8 and export it.

This variable takes precedence over TK_STDIO_DEFAULT_OUTPUT_FORMAT.

TK_PATH_CONVERT 

Determines whether or environment variables that are considered to contain path names are displayed in Windows or UNIX format. When this variable is set to UNIX (this value is case-insensitive), such an enivronment variable is displayed in UNIX format; otherwise, it is displayed in Windows format. See the Environment Variables and Paths section of the EUCM reference page for more information.

TK_UNIX_FILESYSTEM 

When this variable is set, the Enhanced UNIX Compatibility Mode is on and the virtual file system is in use. For more information, see the EUCM reference page.

TK_USE_CTRLD_AS_CONSOLE_EOF 

When set, allows the use of CTRL-D as the EOF (end-of-file) character for the MKS KornShell (including sh, bash, ksh and resh) and MKS C Shell as well as for any utility that can accept input from the console.

In particular, it allows CTRL-D to be used as the EOF (end-of-file) character when completing file names in the C Shell.

verbose 

Is set by the -v command line option and causes the words of each command to be printed after history substitution.

Non-built-in Command Execution

When a command to be executed is found to not be a built-in command the C Shell attempts to execute the command. Each word in the variable path names a directory where the shell attempts to execute the command from. If it is given neither a -c option nor a -t option, the shell hashes the names in these directories into an internal table so that it only tries an exec in a directory if there is a possibility that the command resides there. This shortcut greatly speeds command location when many directories are present in the search path. If this mechanism has been turned off (via unhash), or if the shell was given a -c option or a -t option, and in any case, for each directory component of path that does not begin with x:/ or //, the shell concatenates with the given command name to form a path name of a file that it then attempts to execute.

Parenthesized commands are always executed in a subshell. Thus 

(cd ; pwd) ; pwd

prints the home directory; leaving you where you were (printing this after the home directory), while 

cd ; pwd

leaves you in the home directory. Parenthesized commands are most often used to prevent chdir from affecting the current shell.

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, 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 path name 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 change.

Signal Handling

The shell ignores quit signals. Jobs running in the background are immune to signals generated from the keyboard, including hangups. Other signals have the values that the shell inherited from its parent. The shell's handling of interrupts and terminate signals in shell scripts can be controlled by onintr. Login shells catch the terminate signal; otherwise, this signal is passed on to children from the state in the shell's parent. Interrupts are not allowed when a login shell is reading the file logout.csh.

AUTHOR

William Joy. Job control and directory stack features first implemented by J.E. Kulp of IIASA, Laxenburg, Austria, with different syntax than that used now. File name completion code written by Ken Greer, HP Labs. Eight-bit implementation Christos S. Zoulas, Cornell University.

FILES

~/cshrc.csh 

Is read at the beginning of execution by each shell.

~/login.csh 

Is read by a login shell, after cshrc.csh at login.

~/logout.csh 

Is read by a login shell, at logout.

$TMPDIR/heredoc_csh* 

Is a temporary file used for <<.

LIMITATIONS

csh has the following limits:

BUGS

When a command is restarted from a stop, the shell prints the directory it started in if this is different from the current directory; this can be misleading (that is, wrong) as the job may have changed directories internally.

Alias substitution is most often used to clumsily simulate shell procedures; shell procedures should be provided instead of aliases.

Commands within loops, prompted for by ?, are not placed on the history list. Control structure should be parsed instead of being recognized as built-in commands. This would allow control commands to be placed anywhere, to be combined with |, and to be used with & and ; metasyntax.

It should be possible to use the : modifiers on the output of command substitutions.

AVAILABILITY

PTC MKS Toolkit for Power Users
PTC MKS Toolkit for System Administrators
PTC MKS Toolkit for Developers
PTC MKS Toolkit for Interoperability
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Commands:
sh

PTC MKS Toolkit 10.5 Documentation Build 40.