CSH(1) DOMAIN/IX SYS5 CSH(1)
NAME
csh - a shell (command interpreter) with C-like syntax
USAGE
csh [ options ] [ arg ... ]
DESCRIPTION
Csh is a command language interpreter that uses a history
mechanism, job control facilities, and a C-like syntax.
It begins by executing commands from the .cshrc file in your
home directory. If this is a log-in shell, then it also
executes commands from your .login file. Frequently, CRT
users place an stty crt command in their .login file, and
also invoke tset(1) there.
Normally, the shell then begins reading commands from the
terminal, prompting with a percent sign (%). Upon reading a
line of command input, the shell breaks it into words,
places this sequence of words on the command history list,
parses it, and then executes each command in the current
line.
When a log-in shell terminates, it executes commands from
the .logout file in your home directory.
LEXICAL STRUCTURE
Usually, csh splits input lines into words at blanks and
tabs. The following, however, are exceptions to this:
1. An ampersand (&), pipe (|), semicolon (;), greater-than
(>), less-than (<), or parenthethical character forms
separate words. If these characters are doubled in pairs,
the pairs form single words. You can make these parser
metacharacters a part of other words or prevent their spe-
cial meaning by preceding them with a backslash (\). A new-
line preceded by a backslash is equivalent to a blank.
2. Strings enclosed in matched pairs of quotations, form
parts of a word; metacharacters in these strings, including
blanks and tabs, do not form separate words. Within pairs
of single or double quotations, a newline preceded by a
backslash gives a true newline character.
3. When the shell's input is not a terminal, a pound sign
(#) introduces a comment that continues to the end of the
input line. To prevent this special meaning, you may pre-
cede the comment by a backslash and place it in single quo-
tation marks, or place it in double quotation marks.
Printed 12/4/86 CSH-1
CSH(1) DOMAIN/IX SYS5 CSH(1)
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 pipe (|) characters
forms a pipeline. The output of each command in a pipeline
is connected to the input of the next. You can separate a
series of pipelines by a semicolon (;) to signal the sequen-
tial execution of commands. If you follow this sequence
with an ampersand (&), csh processes these pipelines in the
background.
Any of the above may be placed in parentheses to form a sim-
ple command (which may be a component of a pipeline, etc.)
You can also separate pipelines with double pipe characters
(||) or double ampersands (&&) to indicate, as in the C
language, that the second is to be executed only if the
first fails or succeeds respectively.
JOBS
Csh associates a job with each pipeline. It keeps a table
of current jobs, printed by the jobs command, and assigns
them small integer numbers. When a job is started asynchro-
nously with an ampersand (&), csh prints a line similar to
the following:
[1] 1234
This indicates that the job, which was started asynchro-
nously, was job number 1 and had one (top-level) process
whose process ID was 1234.
To stop a job, you must execute an interrupt (usually a con-
trol key bound by the Display Manager). Once csh has indi-
cated that the job has been stopped (by printing a prompt),
you can manipulate the state of this job. You may put it in
the background with the bg command, or run some other com-
mands and then eventually bring the job back into the fore-
ground with the foreground command, fg. A suspend (normally
a ↑Z) takes effect immediately, causing csh to discard pend-
ing output and unread input. Note that, to set the suspend
character in a pad, you must give the following command from
the Display Manager: kd ^Z dq-c 120028 ke. On a CRT, use
the stty(1) command.
A job being run in the background stops if it tries to read
from the terminal. Background jobs are normally allowed to
produce output, but you can disable this by giving the stty
tostop command. Setting this TTY option causes background
jobs to stop when they try to produce output in the same
manner as they do when they read input.
CSH-2 Printed 12/4/86
CSH(1) DOMAIN/IX SYS5 CSH(1)
There are several ways to refer to jobs in the shell. A
percent sign (%) introduces a job name. Job number 1, for
example, becomes %1. Naming a job brings it to the fore-
ground; thus, %1 is a synonym for fg%1, bringing job 1 back
into the foreground. Similarly, specifying %1 & resumes job
1 in the background. Jobs can also be named by prefixes of
the string typed in to start them, if these prefixes are
unambiguous. Therefore, %ex normally restarts a suspended
ex(1) job, if there is only one suspended job whose name
began with the string ex. It is also possible to specify
%?string to indicate a job whose text contains string, if
there is only one such job.
Csh maintains a notion of the current and previous jobs. In
output pertaining to jobs, it marks the current job with a
plus sign (+), and the previous job with a minus sign (-).
A percent and a plus sign (%+) refers to the current job,
and a percent and minus sign (%-) refers to the previous
job. For close analogy with the syntax of the history
mechanism (described below), a double percent sign (%%) also
represents the current job.
STATUS REPORTING
Csh knows immediately when the state of a process changes.
It normally informs you whenever a job becomes blocked so
that no further progress is possible, but only just before
it prints a prompt. If, however, you set the notify shell
variable, csh immediately reports status changes in back-
ground jobs. The notify shell command also marks a single
process so that its status changes are immediately reported.
By default, notify marks the current process. Thus, you
only have to type notify after starting a background job to
mark it.
If you attempt to leave the shell while jobs are stopped, a
warning message will appear. The jobs command allows you to
see which jobs are affected. A second attempt to exit
causes the suspended jobs to terminate without warning.
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 much confidence. History
substitutions begin with an exclamation point (!) and may
start anywhere in the input stream (providing that they do
not nest). Precede the exclamation point with a backslash
(\) to prevent its special meaning. For convenience, the
character is passed unchanged when it is followed by a
Printed 12/4/86 CSH-3
CSH(1) DOMAIN/IX SYS5 CSH(1)
blank, tab, newline, equal sign, or left parenthesis. His-
tory substitutions also occur when an input line begins with
a caret (^). Before being executed, input lines containing
history substitution are echoed on the terminal as they
could have been typed without history substitution.
Csh saves input commands consisting of one or more words on
the history list. The history substitutions reintroduce
sequences of words from these saved commands into the input
stream, the size of which is controlled by the history vari-
able. The previous command is always retained, regardless
of its value. Commands are numbered sequentially from one
(1).
As an example, consider the following output from the his-
tory command:
9 write michael
10 ex 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
exclamation point (!) in the prompt string.
With the current event 13, you can refer to previous events
by event number, as in !11 for event 11; relatively, as in
!-2 for event 11; by a prefix of a command word, as in !d
for event 12 or !wri 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 modification, simply reintro-
duce the words of the specified events, each separated by a
single blank. As a special case, double exclamation points
(!!) refer to the previous command. Thus, !! alone is
essentially another way of performing what the redo shell
command usually does.
To select words from an event, you 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, etc. The basic word designators
are as follows:
CSH-4 Printed 12/4/86
CSH(1) DOMAIN/IX SYS5 CSH(1)
0 First (command) word
n Nth argument
^ First argument, i.e., 1
$ Last argument
% Word matched by (immediately preceding) ?s? search
x-y Range of words
-y Abbreviation of 0-y
* Abbreviation of ^-$ (or nothing if only 1 word in
event)
x* Abbreviation of x-$
x- Like x*, but omitting word $
You can omit the colon (:) separating the event specifica-
tion from the word designator, if the argument selector
begins with a caret (^), dollar sign ($), asterisk (*), or
percent (%). Furthermore, you can place a sequence of
modifiers after the optional word designator, preceding each
modifier with a colon (:).
Csh defines the following modifiers:
h Remove a trailing pathname component, leaving the
head
r Remove a trailing .xxx component, leaving the root
name
e Remove all but the extension .xxx part
s/l/r/ Substitute l for r
t Remove all leading pathname components, leaving
the tail
& Repeat the previous substitution
g Apply the change globally, prefixing the above,
e.g., g&
p Print the new command but do not execute it
Printed 12/4/86 CSH-5
CSH(1) DOMAIN/IX SYS5 CSH(1)
q Quote the substituted words, preventing further
substitutions
x Like q, but break into words at blanks, tabs, and
newlines
Unless preceded by a g, the modification is applied only to
the first modifiable word. With substitutions, every word
should be applicable or an error occurs.
The left-hand side of substitutions are not regular expres-
sions in the sense of the editors, but rather they are
strings. Any character may be used as the delimiter in
place of a regular slash mark (/). A backslash (\) quotes
the delimiter into the l and r strings. The ampersand char-
acter (&) in the right-hand side is replaced by the text
from the left. A backslash also quotes an ampersand (&). A
null l uses the previous string either from an l or from a
contextual scan string s in !?s?. The trailing delimiter in
the substitution, as well as the trailing question mark (?)
in a contextual scan, may be omitted if a newline follows
immediately.
A history reference can be given without an event specifica-
tion, e.g., !$. In this case, the reference is to the pre-
vious command unless a previous history reference occurred
on the same line (in which case this form repeats the previ-
ous 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 nonblank character of an input line is a caret
(^). This is equivalent to !:s^ and provides a convenient
shorthand for substitutions on the text of the previous
line. Thus, ^lb^lib fixes the spelling of lib in the previ-
ous command. Finally, a history substitution may be sur-
rounded with braces ({ }) 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
with la.
QUOTATIONS WITH SINGLE AND DOUBLE QUOTES
Placing strings in single and double quotes prevents all or
some of the remaining substitutions. Those enclosed in sin-
gle quotes are prevented any further interpretation; those
in double quotes may be expanded as described below.
CSH-6 Printed 12/4/86
CSH(1) DOMAIN/IX SYS5 CSH(1)
In both cases, the resulting text becomes all or part of a
single word. In only one special case (see COMMAND SUBSTI-
TUTION below) does a double-quoted string yield parts of
more than one word; single-quoted strings never do.
ALIAS SUBSTITUTION
Csh maintains a list of aliases that can be established,
displayed, and modified by the alias and unalias commands.
After it scans a command line, the shell parses the line
into distinct commands and checks the first word of each
command, left-to-right, for an alias. If it finds one, csh
rereads the text that is the alias for that command (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.
For example, if the alias for ls is ls -l, the command ls
/usr would map to ls -l /usr, the argument list here being
undisturbed. Similarly, if the alias for lookup was grep !^
/etc/passwd, then lookup bill would map to grep bill
/etc/passwd.
Every time the shell finds an alias, it transforms the input
text and begins the aliasing process 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. Thus, you can aliasprint'pr\!*|lpr' to make a
command that does a pr(1) on its arguments to the line
printer.
VARIABLE SUBSTITUTION
Csh maintains a set of variables, each having as value a
list of zero or more words. The shell sets some of these
variables, and merely refers to others. 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.
You may display and change the values of variables 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 that causes com-
mand input to be echoed. The setting of this variable
results from the -v command line option.
Printed 12/4/86 CSH-7
CSH(1) DOMAIN/IX SYS5 CSH(1)
Other operations treat variables numerically. The command
represented by the at sign (@) permits numeric calculations
to be performed, with the result assigned to a variable.
Variable values are, however, always represented as (zero or
more) strings. In numeric operations, the null string is
considered to be zero, and the second and subsequent words
of multiword values are ignored.
After csh has aliased and parsed the input line, and before
executing each command, it performs variable substitution
keyed by dollar sign ($) characters. This expansion can be
prevented by preceding the dollar sign ($) with a backslash
(\), except within double quotes ("), where it always
occurs, and within single quotes (') where it never occurs.
Strings quoted by a single quote are interpreted later (see
COMMAND SUBSTITUTION below), so the dollar sign ($) substi-
tution does not occur there until later, if at all. A dol-
lar sign ($) 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. Therefore, the first (command) word to this point
can generate more than one word; the first word becomes the
command name, and the rest become arguments.
Unless enclosed in double quotes or given the :q modifier,
the results of variable substitution may eventually be com-
mand and filename 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 will expand to multiple
words with each word separated by a blank and quoted to
prevent later command or filename substitution.
The following metasequences are provided to introduce vari-
able values into the shell input. Except as noted, you can-
not reference a variable that is not set. You may apply the
:h,:t,:r, and :gr modifiers to most of the substitutions
below. Ones that you cannot do this with are marked accord-
ingly. If braces appear in the command form, then the
modifiers must appear within the braces. Only one modifier
beginning with a colon (:) can be applied on each expansion
preceded by a dollar sign ($).
$name
${name} Replace text by the words of the value of
variable name, each separated by a blank.
CSH-8 Printed 12/4/86
CSH(1) DOMAIN/IX SYS5 CSH(1)
Braces insulate name from following charac-
ters, which 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. If name is not a shell
variable, but is set in the environment, then
that value is returned. However, colon (:)
modifiers and the other forms given below are
not available in this case.
$name[selector]
${name[selector]}
Select only some of the words from the value
of name. The selector is subjected to dollar
sign ($) substitution and may consist of a
single number or two numbers separated by a
dash (-). 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 asterisk (*)
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} Give the number of words in the variable.
This is useful for later use in a [selector].
$0 Substitute 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[*].
$?name
${?name} Substitute the string 1 if name is set, 0 if
it is not. This substitution may not be
modified with modifiers preceded by a colon
(:).
$?0 Substitute 1 if the current input filename is
known, 0 if it is not. This substitution may
not be modified with modifiers preceded by a
colon (:).
Printed 12/4/86 CSH-9
CSH(1) DOMAIN/IX SYS5 CSH(1)
$$ Substitute the decimal process number of the
parent shell. This substitution may not be
modified with modifiers preceded by a colon
(:).
$< Substitute a line from the standard input,
with no further interpretation. Useful for
reading from the keyboard in a shell script.
This substitution may not be modified with
modifiers preceded by a colon (:).
COMMAND SUBSTITUTION
Csh applies the remaining substitutions, command and
filename substitution, selectively to the arguments of
built-in commands. This means that portions of expressions
not evaluated are not subjected to these expansions. Names
for commands that are not internal to the shell are 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.
Enclosing a command in backquotes indicates command substi-
tution. Csh usually breaks the output from such a command
into separate words at blanks, tabs, and newlines. It dis-
cards null words, and uses the modified text to replace 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 substitu-
tion to yield only part of a word, even if the command out-
puts a complete line.
If a word contains an asterisk (*), question mark (?), left
bracket ([), or left brace ({), or it begins with a tilde
(~), then that word is a candidate for filename substitu-
tion, also known as ``globbing.'' Csh regards the word as a
pattern, replacing it with an alphabetically sorted list of
filenames that match the pattern. In a list of words speci-
fying filename substitution, at least one pattern must match
an existing filename, but each pattern need not match. Only
an asterisk (*), question mark (?), and left bracket ([)
imply pattern matching. The tilde (~) and left brace ({)
are like abbreviations.
FILE SUBSTITUTION
In matching filenames, you must match a period (.) at the
beginning of a filename or immediately following a regular
slash (/) explicitly. This is also true for the slash
itself. An asterisk (*) matches any string of characters,
CSH-10 Printed 12/4/86
CSH(1) DOMAIN/IX SYS5 CSH(1)
including the null string. A question mark (?) matches any
single character. The sequence [...] matches any one of the
characters enclosed. Within such a sequence, a pair of
characters separated by a backslash (\) matches any charac-
ter lexically between the two.
A tilde (~) at the beginning of a filename refers to home
directories. Standing alone, it expands to your home direc-
tory (reflected in the value of the variable home). When
followed by a name consisting of letters, digits, and dashes
(-), csh searches for a user with that name and substitutes
his or her home directory. Thus, ~ken might expand to
/usr/ken and ~ken/chmach to /usr/ken/chmach. If a tilde is
followed by a character other than a letter or slash (/), or
if it appears somewhere other than at the beginning of a
word, the shell leaves it undisturbed.
The metanotation a{b,c,d}e is a shorthand for abe ace ade.
Left-to-right order is preserved. The results of matching
are sorted separately at a low level to preserve this order
(nesting is acceptable). Thus, ~source/s1/{oldls,ls}.c
expands to /usr/source/s1/oldls.c /usr/source/s1/ls.c
whether or not these files exist without any 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 matching *box.)
As a special case, the shell passes all single unmatched
braces or an empty pair of braces undisturbed.
INPUT/OUTPUT
To redirect the standard input and standard output of a com-
mand, use the following syntax:
< name Open the file name (which is first variable-,
command-, and filename-expanded) as the standard
input.
<< word Read the shell input up to a line identical to
word. Word is not variable-, filename-, or
command-substituted. Each input line is compared
to word before any substitutions are done on this
input line. Unless a quoting backslash (\), dou-
ble quotation ("), or backquote (') character
appears in word, csh performs variable and command
substitution on the intervening lines, allowing
the backslash to quote a dollar sign ($), a
backslash (\), and backquotes ( '). Commands that
are substituted have all blanks and tabs
preserved. All newlines except for the final one
are also preserved. The resulting text is placed
Printed 12/4/86 CSH-11
CSH(1) DOMAIN/IX SYS5 CSH(1)
in an anonymous temporary file, which is given to
the command as standard input.
> name
>! name
>& name
>&! name Use the file name as standard output. If the file
does not exist, create it; if the file does exist,
truncate it, discarding its previous contents.
If the variable noclobber is set, then the file
must not exist, or it must be a character special
file (e.g., a terminal or /dev/null), or an error
results. This helps prevent accidental destruc-
tion of files. An exclamation point (!)
suppresses this check.
Forms involving an ampersand (&) route the diag-
nostic output into the specified file, as well as
the standard output. Name is expanded in the same
way as input filenames beginning with a less-than
character (<) are.
>> name
>>& name
>>! name
>>&! name Use the file name as standard output, but place
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 beginning
with an exclamation point (!) is given.
A command receives the environment in which the 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 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 identified with doubled less-than
characters (<<) should be used to present in-line 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 /dev/null.
Rather, 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 will
block and you are notified (see JOBS above.)
CSH-12 Printed 12/4/86
CSH(1) DOMAIN/IX SYS5 CSH(1)
Diagnostic output may be directed through a pipe with the
standard output. Simply use an ampersand (&) after the pipe
(|) to do this.
EXPRESSIONS
A number of the built-in commands take expressions that have
operators similar to those used for C language, with the
same precedence. These expressions appear in the @, exit,
if, and while commands. The following operators are avail-
able:
|| && | & == != =~ !~
<= >= < > << >> + - * / % ! ~ ( )
Here the precedence increases to the right, The following
characters are, in groups, at the same level:
== != =~ !~
<= >= < >
<< >>
+ -
* / %
The following operators compare their arguments as strings:
== != =~ !~
All others operate on numbers. The operators =~ and !~ are
like == and != except that the right-hand side is a pattern
(containing, for example, asterisks, question marks, and
instances of [...] characters) against which the left-hand
operand is matched. This reduces the need for using the
switch statement in shell scripts when all that is really
needed is pattern-matching.
Csh considers strings beginning with a zero to be octal
numbers. It interprets null or missing arguments as zero.
The result of all expressions are strings, which represent
decimal numbers. It is important to note that no two com-
ponents of an expression can appear in the same word. You
should surround them by spaces, except when they are adja-
cent to components of expressions that are syntactically
significant to the parser (e.g., ampersands, pipe
Printed 12/4/86 CSH-13
CSH(1) DOMAIN/IX SYS5 CSH(1)
characters, etc.).
Also available in expressions as primitive operands are com-
mand executions enclosed in braces ({ and }), and file
enquiries of the form -l name where l is one of the follow-
ing:
r read access
w write access
x execute access
e existence
o ownership
z zero size
f plain file
d directory
Csh performs command and filename expansion on the specified
name, and then checks to see if it has the specified rela-
tionship to the real user. If the file does not exist, or
if it is inaccessible, then all inquiries return false (0).
Command executions succeed, returning true (1), if the com-
mand exits with status 0; otherwise, they fail, returning
false (0). If you require more detailed status information,
execute the command outside an expression and examine the
status variable.
CONTROL FLOW
Csh contains a number of commands 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, due to 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 below.
If the shell's input is not seekable, the shell buffers
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, backward gotos
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 executed in a sub-shell.
CSH-14 Printed 12/4/86
CSH(1) DOMAIN/IX SYS5 CSH(1)
alias
Print all aliases.
alias name
Print the alias for name.
alias name wordlist
Assign the specified wordlist as the alias of name. The
wordlist is command- and filename-substituted. Name is
not allowed to be alias or unalias.
alloc
Show the amount of dynamic core in use, broken down
into used and free core, and the address of the last
location in the heap. With an argument, this command
shows each used and free block on the internal dynamic
memory chain, indicating its address, size, and status
(used or free). This is a debugging command and may
not work in production versions of the shell. It
requires a modified version of the system memory allo-
cator.
bg
bg %job ...
Put the current or specified jobs into the background,
continuing them if they were stopped.
break
Resume execution after the end of the nearest enclosing
foreach or while. Execute the remaining commands on the
current line. Multi-level breaks are thus possible by
writing them all on one line.
breaksw
Break from a switch, resuming after the endsw.
case label:
Specify a label in a switch statement.
cd
cd name
chdir
chdir name
Change the shell's working directory to directory name.
If no argument is given, 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 a slash (/), or a
slash preceded by one or two periods (./ or ../), check
Printed 12/4/86 CSH-15
CSH(1) DOMAIN/IX SYS5 CSH(1)
each component of the variable cdpath to see if it has
a subdirectory name. Finally, if all else fails but
name is a shell variable whose value begins with a
slash, check to see if it is a directory.
continue
Continue execution of the nearest enclosing while or
foreach. Execute remaining commands on the current
line.
default:
Label the default case in a switch statement. This
command should follow all case labels.
dirs Print the directory stack. The top of the stack is at
the left, and the first directory in the stack is the
current directory.
echo wordlist
echo -n wordlist
Write the specified words to the shell's standard out-
put, separated by spaces, and terminated with a newline
(unless the -n option is specified).
else
end
endif
endsw
See the description of the foreach, if, switch, and
while statements below.
eval arg ...
Read the arguments as input to the shell, executing the
resulting command(s) in the context of the current
shell. This occurs as in sh(1). The command is gen-
erally used to execute commands generated as the result
of command or variable substitution, since parsing
occurs before these substitutions. See tset(1) for an
example of using eval.
exec command
Execute the specified command in place of the current
shell.
exit Exit with the value of the status variable.
exit (expr)
Exit with the value of the specified expr.
fg
CSH-16 Printed 12/4/86
CSH(1) DOMAIN/IX SYS5 CSH(1)
fg %job ...
Bring the current or specified jobs into the fore-
ground, continuing them if they were stopped.
foreach name (wordlist)
...
end Successively set the variable name to each member of
wordlist, and execute the sequence of commands between
this command and the matching end. (Both foreach and
end must appear alone on separate lines.)
Use the continue command to continue the loop prema-
turely. Use the break command to terminate it prema-
turely. When the shell reads this command from the
terminal, it reads the loop once, prompting with a
question mark (?) before executing any statements in
the loop. If you make a mistake typing in a loop at
the terminal, you can interrupt it by typing dq -i.
glob wordlist
Perform the same function as the echo command, but do
not recognize backslash escapes, and delimit words by
null characters in the output. Use this command with
programs that use the shell to filename-expand a list
of words.
gotoword
Perform filename- and command-expansion on the speci-
fied word to yield a string of the form label. Cause
the shell to rewind input as much as possible and
search for a line of the form label: (possibly preceded
by blanks or tabs). Continue execution after the
specified line.
hashstat
Print a statistics line indicating how effective the
internal hash table has been at locating commands and
avoiding instances of the exec command. An exec is
attempted for each component of the path where the hash
function indicates a possible hit, and in each com-
ponent that does not begin with a slash.
history
Display the history event list.
history n
Print only the n most recent events in the history
event list.
history -r n
Printed 12/4/86 CSH-17
CSH(1) DOMAIN/IX SYS5 CSH(1)
Print the most recent (rather than the oldest) events
in the history event list.
history -h n
Print the history event list without leading numbers.
Use this command to produce files suitable for sourcing
with the -h option to the source built-in command.
if (expr) command
If the specified expression evaluates true, then exe-
cute the single command with arguments. Variable sub-
stitution on command happens early, at the same time it
does for the rest of the if command. The 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, when command is not exe-
cuted.
if (expr) then
...
else if (expr2) then
...
else
...
endif
If the specified expr is true, then execute the com-
mands to the first else; if else if expr2 is true, then
execute the commands to the second else, etc. Any
number of else-if pairs are possible; only one endif is
needed. The else part is 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.)
inlib pathname
Install a user-supplied library specified by pathname
at the current shell program level. The library
remains installed until the shell that installed it
exits. User-inlibed libraries are only available to
programs that are run in-process. Look under the
description of in-process execution given in the prede-
fined variable section of this manual entry. Also
refer to the description of the DOMAIN command /com/lib
in the DOMAIN System Command Reference.
jobs List the active jobs.
jobs -l
List the active jobs, but also include process IDs.
CSH-18 Printed 12/4/86
CSH(1) DOMAIN/IX SYS5 CSH(1)
kill %job
kill -sig %job ...
kill pid
kill -sig pid ...
kill -l
Send either the TERM (terminate) signal or the speci-
fied signal to the jobs or processes indicated. Pro-
vide signals by number or by names (as given in
/usr/include/signal.h, stripped of the SIG prefix. A
kill -l lists the signal names. There is no default
for this command. A kill alone on the command line does
not send a signal to the current job. If the signal
being sent is TERM (terminate) or HUP (hangup), then
the job or process will be sent a CONT (continue) sig-
nal as well.
login
Terminate a log-in shell, replacing it with an instance
of /bin/login. This is one way to log off, and it is
included for compatibility with sh(1).
logout
Terminate a log-in shell. This command is especially
useful if ignoreeof is set.
nice Set the nice(1) increment for this shell to 4.
nice +number
Set the nice(1) increment to the given positive number.
nice command
Run command at nice(1) priority 4.
nice +number command
Run command at positive number nice(1) priority. The
command is always executed in a sub-shell, and the res-
trictions placed on commands in simple if statements
apply.
nohup
When used in a shell script, ignore hangups for the
remainder of the script.
nohup command
Run the specified command with hangups ignored. This
happens to all processes detached with an ampersand
(&).
notify
notify %job ...
Printed 12/4/86 CSH-19
CSH(1) DOMAIN/IX SYS5 CSH(1)
Notify the user asynchronously when the status of the
current or specified jobs changes (normally, notifica-
tion is presented before a prompt). This is automatic,
if the shell variable notify is set.
onintr
Restore the default action of the shell on interrupts
(to terminate shell scripts or to return to the termi-
nal command input level). In any case, if the shell is
running detached and interrupts are being ignored, all
forms of onintr have no meaning, and interrupts con-
tinue to be ignored by the shell and all invoked com-
mands.
onintr -
Ignore all interrupts.
onintrlabel
Execute a gotolabel when an interrupt is received or a
child process terminates because it was interrupted.
popd Pop the directory stack, returning to the new top
directory. The elements of the directory stack are
numbered from zero, starting at the top.
popd +n
Discard the nth entry in the directory stack.
pushd
Exchange the top two elements of a directory stack.
pushd name
Change to name directory and push the old current work-
ing directory onto the directory stack.
pushd +n
Rotate the nth argument of the directory stack around
to be the top element and change to it. The members of
the directory stack are numbered from zero, starting at
the top.
rehash
Recompute the internal hash table of the contents of
the directories in the path variable. This is needed if
new commands are added to directories in the path while
you are logged in. This should only be necessary if
you add commands to one of your own directories, or if
someone changes the contents of one of the system
directories.
CSH-20 Printed 12/4/86
CSH(1) DOMAIN/IX SYS5 CSH(1)
repeat count command
Execute the specified command (subject to the same res-
trictions as the command in the one-line if statement
above) count times. I/O redirections occur exactly
once, even if count is zero.
set Show the value of all shell variables. Variables which
have other than a single word as their value print as a
parenthesized word list.
set name
Set name to the null string. In all cases, the value
is command- and filename-expanded.
set name=word
Set name to the single word. In all cases, the value is
command- and filename-expanded.
set name[index]=word
Set the indexth component of name to word. This com-
ponent must already exist. In all cases, the value is
command- and filename-expanded.
set name=(wordlist)
Set name to the list of words in wordlist. In all
cases, the value is command- and filename-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.
setenv name value
Set the value of the environment variable name to be
value, a single string. The most commonly used
environment variables -- USER, TERM, and PATH -- are
automatically imported to and exported from the csh
variables user, term, and path. You do not have to use
setenv for these.
shift
Shift the members of argv to the left, discarding
argv[1]. It is an error for the argv variable not to
be set or to have less than one word as its value.
shift variable
Shift the specified variable to the left.
source name
Read commands from name. You may nest source commands,
but if you nest them too deeply, the shell may run out
Printed 12/4/86 CSH-21
CSH(1) DOMAIN/IX SYS5 CSH(1)
of file descriptors. An error in a source at any level
terminates all nested source commands.
source -h name
Place commands in the history list without executing
them. Normally, input during source commands is not
placed on the history list.
stop Stop the current job that is executing in the back-
ground.
stop %job ...
Stop the specified job that is executing in the back-
ground.
suspend
Cause the shell to stop immediately, much as if it had
been sent a stop signal with ↑Z. This is most often
used to stop shells started by su(1).
switch (string)
casestr1:
...
breaksw
...
default:
...
breaksw
endsw
Successively match each case label against the speci-
fied string, which is first command- and filename-
expanded. The following metacharacters may be used in
the case labels, which are variable-expanded: *, ?, and
[...]. If none of the labels match before a default
label is found, then begin the execution after the
default label. Each case label and the default label
must appear at the beginning of a line. The breaksw
command causes execution to continue after the endsw.
Otherwise, control may fall through case labels and
default labels as in C programs. If no label matches
and there is no default, execution continues after the
endsw.
time Print a summary of time used by this shell and its
children.
time command
Time the specified simple command, and print a time
CSH-22 Printed 12/4/86
CSH(1) DOMAIN/IX SYS5 CSH(1)
summary as described under the time variable. If neces-
sary, create an extra shell to print the time statistic
when the command completes.
umask
Display the file creation mask (in octal).
umask value
Set the file creation mask to the specified value. Com-
mon 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 no write access for users in
the group or others).
unalias pattern
Discard all aliases whose names match the specified
pattern. Thus, all aliases are removed by unalias *.
It is not an error for nothing to be unaliased.
unhash
Disable the internal hash table mechanism normally used
to speed location of executed programs.
unset pattern
Remove all variables whose names match the specified
pattern. Thus, all variables are removed by unset*.
This has noticeably distasteful side-effects. It is
not an error for nothing to be unset.
unsetenv pattern
Remove all variables whose names match the specified
pattern from the environment. Also refer to the setenv
built-in shell command above and the printenv(1) com-
mand.
ver systype
With no arguments, return the current value of the SYS-
TYPE environment variable. With a systype argument,
change the SYSTYPE environment variable to either
bsd4.2 or sys5, depending on which is specified.
wait Wait for all background jobs. If the shell is interac-
tive, then an interrupt can disrupt the wait, at which
time the shell prints names and job numbers of all jobs
known to be outstanding.
while (expr)
...
end While the specified expression evaluates non-zero,
Printed 12/4/86 CSH-23
CSH(1) DOMAIN/IX SYS5 CSH(1)
evaluate the commands between the while and the match-
ing end. You may use break and continue 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.
which
Identify which file would have been executed had the
command been submitted for execution. The command is
submitted to normal alias and variable substitutions.
%job Bring the specified job number into the foreground.
%job &
Continue the specified job in the background.
@ Print the values of all the shell variables.
@ name = expr
Set the specified name to the value of expr. If the
expression contains a greater-than (>), less-than (<),
or pipe (|) character, then you must place at least
that part within parentheses.
@ name[index] = expr
Assign the value of expr to the indexth argument of
name. Both name and its indexth component must already
exist. Operators are available as in C language. 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 double plus (++) and
double minus (--) operators increment and decrement
name respectively, i.e., @ i++.
PREDEFINED AND ENVIRONMENT VARIABLES
The following variables have special meaning to csh. Of
these, argv, cwd, home, path, prompt, Shell, and status are
always set by the shell. Except for cwd and status, this
setting occurs only at initialization. These variables will
not then be modified unless you explicitly perform the
modification.
Csh copies the USER environment variable into the user vari-
able, TERM into term, and HOME into home. It then copies
these back into the environment whenever the normal shell
variables are reset.
CSH-24 Printed 12/4/86
CSH(1) DOMAIN/IX SYS5 CSH(1)
Csh handles the PATH environment variable in a similar
manner. Do not worry about the setting for PATH other than
in the file .cshrc. Inferior csh processes import the defin-
ition of path from the environment, and re-export it if you
then change it.
argv Set to the arguments to the shell. It is
from this variable that positional parameters
are substituted, i.e., $argv[1] replaces $1,
etc.
cdpath Give a list of alternate directories searched
to find subdirectories in cd commands.
cwd Give the full pathname of the current direc-
tory.
echo Echo each command and its arguments just
before the command is executed. This vari-
able is set when the -x command line option
is given. For non-built-in commands all
expansions occur before echoing. Echo
built-in commands before command and filename
substitution, since these substitutions are
then done selectively.
histchars Change the characters used in history substi-
tution, if a string value is specified. Use
the first character of its value as the his-
tory substitution character, replacing the
default exclamation point (!). The second
character of its value replaces the ↑ charac-
ter in quick substitutions.
history Control the size of the history list. If a
numeric value is specified, do not discard
any command that has been referenced in that
many events. Save the last executed command
on the history list. The shell may run out
of memory if the value of history is too
large.
home Represents the home directory of the invoker,
initialized from the environment. The
filename expansion caused by the presence of
a tilde (~) character refers to this vari-
able.
homedirchar Change the character used to refer to the
home directory variable, if a string value is
Printed 12/4/86 CSH-25
CSH(1) DOMAIN/IX SYS5 CSH(1)
specified. Unsetting this variable restores
the tilde (~) as the default character.
ignoreeof If set, ignore the end-of-file from terminal
input devices. This prevents shells from
accidentally being killed by an EOF.
inprocess If set, run new programs in the shell process
(unless part of a pipe or running in back-
ground). When inprocess is set, programs run
by the C shell can access user libraries
installed via the inlib built-in command.
Otherwise, the C shell always spawns a new
process to run a new program. This variable
is normally unset unless it has been set in
the DM (by putting a line of the form ``env
INPROCESS `true` in the file
`node_data/startup.type), or unless the -j
option is used with csh. Commands started
in-process cannot be suspended or manipulated
using the csh job-control facilities.
mail Represent the files where the shell checks
for mail. This is done after each command
completion that results in a prompt, if a
specified interval has elapsed. The shell
will tell you that 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 (10 minutes). If you
specify multiple mail files, the shell will
tell you that you have new mail in name, when
there is mail in the file name.
noclobber Restrict output redirection to insure that
files are not accidentally destroyed, and
that redirections done with >> characters
refer to existing files.
noglob If set, inhibit filename expansion. Use this
in shell scripts that do not deal with
filenames, or after you have obtained a list
of filenames 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.
CSH-26 Printed 12/4/86
CSH(1) DOMAIN/IX SYS5 CSH(1)
It is still an error for the primitive pat-
tern to be malformed, i.e., echo [ still
gives an error.
notify If set, notify the user asynchronously of job
completions. By default, the shell presents
job completions just before printing a
prompt.
path Use each word of the path variable to specify
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 execute.
The usual search path is as follows:
. (period)
/bin
/usr/bin
This, however, may vary from system to sys-
tem. For the super-user, the default search
path is as follows:
/etc
/bin
/usr/bin
A shell that is given neither the -c nor the
-t option will normally hash the contents of
the directories in the path variable after
reading .cshrc, and each time the path vari-
able is reset. If new commands are added to
these directories while the shell is active,
it may be necessary to give the rehash or the
commands may not be found.
prompt Read, from an interactive terminal input, the
string printed before each command. If an
exclamation point (!) appears in the string,
replace it by the current event number
(unless a preceding backslash is given). For
the super-user, the default is a percent (%)
or pound (#) sign.
savehist Give a numeric value to control the number of
history list entries saved in ~/.history at
log-out time. Save any command that has been
referenced in that many events. During
start-up, the shell sources ~/.history into
Printed 12/4/86 CSH-27
CSH(1) DOMAIN/IX SYS5 CSH(1)
the history list, enabling history to be
saved across log-ins. If the value of
savehist is too large, the shell will be slow
during start-up.
shell Represent the file in which the shell
resides. This is used in forking shells to
interpret files that have execute bits set,
but are not executable by the system. This
variable is initialized to the (system-
dependent) home of the shell.
status Give the status returned by the last command.
If it terminated abnormally, add 0200 to the
status. Built-in commands that fail return
exit status 1. All other built-in commands
set status 0.
time Control automatic timing of commands, if a
numeric value is supplied. If set, print the
user, system, and real times for any command
that takes more than this many CPU seconds.
Also print a utilization percentage (the
ratio of user plus system times to real time)
when the command terminates.
verbose Print the words of each command after history
substitution. This variable is set by the -v
command line option to csh.
NON-BUILT-IN COMMAND EXECUTION
When a command to be executed is found to be something other
than a built-in command, csh attempts to execute it via
execve(2). Each word in the variable path names a directory
from which the shell attempts to execute the command. If it
is given neither a -c nor a -t option, the shell hashes the
names in these directories into an internal table so that it
will only try an exec in a directory if the command poten-
tially resides there. This greatly speeds command location
when a large number of directories are present in the search
path. For each directory component of path that does not
begin with a slash (/), the shell concatenates with the
given command name to form a pathname of a file which it
then attempts to execute. The shell also does this if the
internal hash table mechanism has been turned off (via
unhash), or a -c or -t command line option was specified in
csh.
CSH-28 Printed 12/4/86
CSH(1) DOMAIN/IX SYS5 CSH(1)
Commands in parentheses are always executed in a sub-shell.
Thus, (cd ; pwd) ; pwd prints the home directory, leaving
you where you were (printing this after the home directory).
On the other hand, cd ; pwd leaves you in the home direc-
tory. Commands in parentheses are most often used to
prevent chdir from affecting the current shell.
If a file has execute permissions but is not an executable
binary to the system, csh assumes it to be a file containing
shell commands reads it (spawning a new shell to do so if
inprocess is unset).
If there is an alias for shell, then the words of the alias
will be prepended to the argument list to form the shell
command. The first word of the alias should be the full
pathname of the shell (e.g., $Shell). Note that this is a
special, late-occurring, case of alias substitution, and it
only allows words to be prepended to the argument list
without modification.
COMMAND LINE OPTIONS
-c Read commands from the (single) following argument that
must be present. Place any remaining arguments in
argv.
-e Exit if any invoked command terminates abnormally or
yields a non-zero exit status.
-f Start up the shell more quickly than normal. Do not
take time to search for or execute commands from the
.cshrc file in the invoker's home directory.
-i Make the shell interactive, prompting for its top-level
input (even if it does not appear to be a terminal).
shells are interactive without this option if their
inputs and outputs are terminals.
-j Run commands in-process.
-n Parse commands, but do not execute them. This aids in
syntactic checking of shell scripts.
-s Take command input from the standard input.
-t Read and execute a single line of input. A backslash
(\) may be used to escape the newline at the end of
this line and continue onto another line.
-v Set the verbose variable, causing command input to be
echoed after history substitution.
Printed 12/4/86 CSH-29
CSH(1) DOMAIN/IX SYS5 CSH(1)
-x Set the echo variable, so that commands are echoed
immediately before execution.
-V Set the verbose variable even before .cshrc is exe-
cuted.
-X Set the echo variable even before .cshrc is executed.
If argument 0 to the shell is a dash (-), then this is a
log-in shell. If arguments remain after command line
options are processed, but none of the -c, -i, -s, or -t
options was 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.
Since many systems use either the standard version 6 or ver-
sion 7 shells whose shell scripts are not compatible with
this shell, csh executes a standard shell if the first char-
acter of a script is not a pound sign (#), i.e., the script
does not start with a comment. Remaining arguments initial-
ize the argv variable.
SIGNAL HANDLING
Csh normally ignores quit signals. Jobs running detached,
either by an ampersand (&) or the bg or %... & commands, are
immune to signals generated from the keyboard, including
hangups. Other signals have the values which the shell
inherited from its parent. The shell's handling of inter-
rupts and terminate signals in shell scripts can be con-
trolled by onintr. Log-in shells catch the TERM (terminate)
signal. Otherwise, this signal is passed on to children
from the state in the shell's parent. In no case are inter-
rupts allowed when a log-in shell is reading the file
.logout.
CAUTIONS
Words can be no longer than 1024 characters. The system
limits argument lists to 10240 characters. The number of
arguments to a command which involves filename expansion is
limited to one-sixth the number of characters allowed in an
argument list.
Command substitutions 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 sin-
gle line to twenty.
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, since the job
may have changed directories internally.
CSH-30 Printed 12/4/86
CSH(1) DOMAIN/IX SYS5 CSH(1)
Shell built-in functions cannot be stopped and then res-
tarted. Csh does not handle command sequences such as a ; b
; c gracefully when stopping is attempted. If you suspend
b, the shell immediately executes c. This is especially
noticeable if this expansion results from an alias. Place
the sequence of commands in parentheses to force it to a
sub-shell, i.e., ( a ; b ; c ).
Control over TTY output after processes are started is prim-
itive.
Commands within loops, prompted for by a question mark (?),
are not placed in the history list.
Control structure should be parsed rather than being recog-
nized as built-in commands. This allows control commands to
be placed anywhere, to be combined with the pipe character
(|), and to be used with ampersand (&) and semicolon (;)
metasyntax.
You cannot use the colon (:) modifiers on the output of com-
mand substitutions. More than one colon (:) modifier is not
allowed on dollar sign ($) substitutions.
Symbolic links fool the shell. In particular, pathnames
that contain ".." preceeded by a symbolic link always refer
to the "real" parent directory and not the parent directory
of the symbolic link.
FILES
~/.cshrc readatbeginningofexecutionby
~/.login readbylog-inshell,after.cshrc
~/.logout readbylog-inshell,atlog-out
/bin/sh standardshell;forshellscriptsnot
/tmp/sh* temporaryfilefor<<
/etc/passwd sourceofhomedirectoriesfor~name
RELATED INFORMATION
sh(1), environ(5).
Printed 12/4/86 CSH-31