CSH(1) SysV CSH(1)
NAME
csh - a shell (command interpreter) with C-like syntax
SYNOPSIS
csh [ -cefinstvVxX ] [ -Dname=value ] [ arg ... ]
DESCRIPTION
csh is a command-language interpreter that incorporates a history
mechanism (see History Substitutions), job control facilities (see Jobs),
interactive filename and username completion (see Filename Completion),
and a C-like syntax.
csh 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. CRT users often place an stty crt command in
their .login files, and also invoke tset(1) there. To be able to use its
job control facilities, users of csh must (and automatically) use the tty
driver fully described in tty(4). This tty driver allows you to generate
interrupt characters from the keyboard to tell jobs to stop. See stty(1)
for details on setting options in the tty driver.
Normally, the shell then begins reading commands from the terminal,
prompting with "% " . 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 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:
+ The characters: &, |, ;, >, <, (, and ) form separate words. If
doubled in &&, ||, <<, >>, these pairs form single words. You can
make these parser metacharacters part of other words or prevent their
special meaning by preceding them with a \ (backslash) character. A
newline preceded by a backslash is equivalent to a blank.
+ Strings enclosed in matched pairs of quotation marks, ', `, or ", form
parts of a word; metacharacters in these strings, including blanks and
tabs, do not form separate words. Within pairs of ' or " characters,
a newline preceded by a backslash gives a true newline character.
+ When the shell's input is not a terminal, the # character introduces a
comment that continues to the end of the input line. To prevent this
special meaning, you can precede the # by a \ or place it 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 ; characters, and are then executed
sequentially. A sequence of pipelines can be placed in the background by
adding an & character at the end.
Any of the above may be placed in parentheses to form a simple command
(which may be a component of a pipeline, and so on). You can also
separate pipelines with || or && characters to indicate, as in the C
language, that the second is to be executed only if the first fails or
succeeds, respectively (see Expressions).
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 asynchronously with an &, csh prints a
line similar to the following:
[1] 1234
This indicates that the job, which was started asynchronously, was job
number 1 and had one (top-level) process whose process ID was 1234.
To suspend a running job, you must send it a stop signal, usually with
CTRL/Z. Once csh has indicated that the job has been stopped (and has
printed a prompt), you can manipulate the state of this job. You can put
it in the background with the bg command, or run some other commands and
then eventually bring the job back into the foreground with the fg
command. A suspend takes effect immediately, causing csh to discard
pending output and unread input. There is another special key, CTRL/Y,
which does not generate a STOP signal until a program attempts to read(2)
it. Type CTRL/Y ahead when you have prepared some commands for a job
that you wish to stop after the program has read them. CTRL/Y is not
supported in the Display Manager.
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 specifying the stty tostop command. Specifying
stty tostop causes background jobs to stop when they try to produce
output just as they do when they read input.
There are several ways to refer to jobs in the shell. The % character
introduces a job name. Job number 1, for example, becomes %1. Naming a
job brings it to the foreground; 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 the prefix is unambiguous. For
example, %ex normally restarts a suspended ex(1) job, if there is only
one suspended job whose name begins with the string "ex". You can also
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 + 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
history mechanism (described below), a %% 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. (This is so that it
does not otherwise disturb your work.) However, if you set the notify
shell variable, csh immediately reports status changes in background
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.
When you try to leave the shell while jobs are stopped, you are warned
that "You have stopped jobs." You can use the jobs command to see which
jobs are stopped. A second attempt to exit causes the suspended jobs to
terminate without warning.
FILENAME COMPLETION
When the filename completion feature is enabled by setting the shell
variable filec (see set), csh interactively completes filenames and
usernames from unique prefixes, when they are input from the terminal
followed by the escape character (the escape key, or CTRL/L). 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<ESC>
csh completes the prefix "ch" to the only matching filename "chaosnet",
changing the input line to
% vi chaosnet
However, if you specify
% vi D<ESC>
csh expands the input only to
% vi DSC.
and sounds the terminal bell to indicate that the expansion is
incomplete, because two filenames match the prefix "DSC".
If a partial filename is followed by the end-of-file character (usually
CTRL/D), then, instead of completing the name, csh lists all filenames
matching the prefix. For example, the input
% vi D<CTRL/D>
causes all files beginning with "D" to be listed:
DSC.NEW DSC.OLD
while the input line remains unchanged.
You can use the same system of escape and end-of-file to expand partial
usernames, if the word to be completed (or listed) begins with the
character "~". For example, typing
cd ~ro<CTRL/D>
may produce the expansion
cd ~root
Set the variable nobeep, to inhibit the use of the terminal bell to
signal errors or multiple matches.
Normally, all files in the particular directory are candidates for name
completion. Files with certain suffixes can be excluded from
consideration by setting the variable fignore to the list of suffixes to
be ignored.
Thus, if you set fignore by the command
% set fignore = (.o .out)
then typing
% vi x<ESC>
results in the completion to
% vi xmpl.c
ignoring the files xmpl.o and xmpl.out. However, if the only completion
possible requires not ignoring these suffixes, they are not ignored.
Also, fignore does not affect the listing of filenames by CTRL/D. All
files are listed regardless of their suffixes.
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 a
previous command with little typing and much confidence. History
substitutions begin with the character ! and can start anywhere in the
input stream (providing that they do not nest). Precede the ! with a \
to prevent its special meaning. For convenience, a ! is passed unchanged
when it is followed by a blank, tab, newline, =, or (. History
substitutions also occur when an input line begins with a ^ (see below).
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 the history list
is controlled by the history variable. The previous command is always
retained, regardless of its value. Commands are numbered sequentially
from 1.
For example, consider the following output from the history 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 you can make the current event number
part of the prompt by placing an ! in the prompt string.
Supposing the current event is 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 reintroduce the words
of the specified events, each separated by a single blank. As a special
case, !! refer to the previous command. Thus, !! alone is essentially a
redo.
To select words from an event, you 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 first (command) word
n n'th argument
^ first argument, i.e. `1'
$ last argument
% word matched by (immediately preceding) ?s? search
x-y range of words
-y abbreviates `0-y'
* abbreviates `^-$', or nothing if only 1 word in event
x* abbreviates `x-$'
x- like `x*' but omitting word `$'
The : separating the event specification from the word designator can be
omitted if the argument selector begins with a ^, $, * - or %. After the
optional word designator can be placed a sequence of modifiers, each
preceded by a :. The following modifiers are defined:
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.
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, it is an error for no word to be
applicable.
The left-hand side of substitutions are not regular expressions in the
sense that they are in the editors (ed, vi, and so on) rather they are
strings. You can use any character as the delimiter in place of a /. A
\ quotes the delimiter into the l and r strings. The character & on the
right-hand side is replaced by the text from the left. A \ also quotes
an &. 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 ? in a contextual scan, can be
omitted if a newline follows immediately.
You can specify a history reference without an event specification, for
example, !$. In this case, 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^ and
provides a convenient shorthand for substitutions on the text of the
previous line. Thus, ^lb^lib fixes the misspelling 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 type !{l}a to do ls -ld ~paula while
!la looks for a command starting with la.
QUOTATIONS WITH SINGLE AND DOUBLE QUOTES
Placing strings in single and double quotation marks prevents all or some
of the remaining substitutions. Those enclosed in single quotation marks
are prevented any further interpretation; those in double quotation marks
may be expanded as described below.
In both cases, the resulting text becomes all or part of a single word.
In only one special case (see COMMAND SUBSTITUTION 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, csh parses the line into distinct commands and checks the first
word of each command, left-to-right, for an alias. If it finds one, it
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, csh leaves the argument list
unchanged.
For example, if the alias for ls is ls -l, the command ls /usr maps to ls
-l /usr and the argument list is undisturbed. Similarly, if the alias
for lookup is grep !^ /etc/passwd, then lookup bill maps to grep bill
/etc/passwd.
Every time csh finds an alias, it transforms the input text and begins
the aliasing process again on the reformed input line. Prevent looping
(if the first word of the new text is the same as the old) by flagging
the first word to prevent further aliasing. csh detects other loops and
returns an error.
Note that the mechanism allows aliases to introduce parser metasyntax.
Thus, you can specify alias print 'pr \!* | lpr' to make a command that
pr's 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. csh 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 its value are referred to in special ways.
You can display and change the values of variables by using the set and
unset commands. Some of the variables the shell refers to are toggles.
The shell does not care what their value is, only whether they are set.
For instance, the verbose variable is a toggle that causes command input
to be echoed. Use the command line option -v to set this variable.
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. However, variable values are 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 $ characters.
You can prevent this expansion by preceding the $ with a \, except within
double quotation marks ("), where it always occurs, and within single
quotation marks (') where it never occurs. Strings enclosed in single
quotation marks are interpreted later (see COMMAND SUBSTITUTION below),
so the dollar sign ($) substitution does not occur until later, if at
all. A $ 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 you enclose the results of variable substitution in double
quotation marks or specify the :q modifier, they may eventually be
command and filename substituted. Within double quotation marks, a
variable whose value consists of multiple words expands to a portion of a
single word, with the words of the variable's value separated by blanks.
When the :q modifier is applied to a substitution, the variable expands
to multiple words with each word separated by a blank and enclosed in
quotation marks to prevent later command or filename substitution.
The following metasequences are provided to introduce variable values
into the shell input. Except as noted, you cannot reference a variable
that is not set. You can apply the :h, :t, :r, :gh, :gt, and :gr
modifiers to most of the substitutions below. Substitutions that you
cannot do this with are marked accordingly. If braces appear in the
command form, you must put the modifiers within the braces. You can
apply only one modifier beginning with a colon (:) 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. Braces insulate name from
following characters, 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, 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 $ 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
you omit the first number of a range, the number defaults
to 1. If you omit the last member of a range, the number
defaults to $#name. The selector * selects all words. It
is not an error for a range to be empty if you omit the
second argument or it is in range.
$#name
${#name} Give the number of words in the variable. This is useful
for later use in a "[selector]".
$0 Substitute the filename from which command input is being
read. An error occurs if the name is not known. This
substitution cannot be modified with modifiers preceded by
a :.
$number
${number} This sequence is equivalent to $argv[number].
$* This sequence is equivalent to $argv[*].
$?name
$?{name} Substitute the string 1 if name is set; 0 if it is not.
This substitution cannot be modified with modifiers
preceded by a :.
$?0 Substitute 1 if the current input filename is known; 0 if
it is not. This substitution cannot be modified with
modifiers preceded by a :.
$$ Substitute the decimal process number of the parent shell.
This substitution cannot be modified with modifiers
preceded by a :.
$< Substitute a line from the standard input, with no further
interpretation. This sequence is useful for reading from
the keyboard in a shell script. This substitution cannot
be modified with modifiers preceded by a :.
COMMAND AND FILENAME 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 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 indicated by a command enclosed in "`". csh
usually breaks the output from such a command into separate words at
blanks, tabs, and newlines. It discards null words, and uses the
modified text to replace the original string. Within double quotation
marks, only newlines force new words; blanks and tabs are preserved.
In any case, the single final newline does not force a new word. Note
that it is thus possible for a command substitution to yield only part of
a word, even if the command outputs a complete line.
FILENAME SUBSTITUTION
If a word contains any of the characters *, ?, [, {, or it begins with ~,
that word is a candidate for filename substitution, 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 specifying filename substitution, at least one pattern must
match an existing filename, but each pattern need not match. Only the
metacharcters *, ?, and [ imply pattern matching. The characters ~ and {
are like abbreviations.
In matching filenames, you must match a . at the beginning of a filename
or immediately following a / explicitly. This is also true for the /
itself. An * matches any string of characters, including the null
string. A ? matches any single character. The sequence [...] matches
any one of the characters enclosed. Within such a sequence, a pair of
characters separated by a - matches any character lexically between the
two.
The character ~ at the beginning of a filename refers to home
directories. Standing alone, it expands to your home directory
(reflected in the value of the variable home). When the ~ is followed by
a name consisting of letters, digits, and -, csh searches for a user with
that name and substitutes his home directory. Thus, ~ken might expand to
/usr/ken and ~ken/chmach to /usr/ken/chmach. If the ~ is followed by a
character other than a letter or /, 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 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 command, 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 subjected to variable-, filename-, or command-substitution.
Each input line is compared to word before any substitutions
are done on this input line. Unless a quoting \, ", or '
character appears in word, csh performs variable and command
substitution on the intervening lines, allowing \ to quote a $,
a \, and `. 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 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, the file must not exist, or
it must be a character special file (for example, a terminal or
/dev/null), or an error results. This helps prevent accidental
destruction of files. The ! forms suppress this check.
Forms involving & route the diagnostic output, as well as the
standard output, into the specified file. name is expanded in
the same way as input filenames beginning with < are.
>> name
>>& name
>>! name
>>&! name Use the file name as standard output, like >, but place output
at the end of the file. If the variable noclobber is set, it
is an error for the file not to exist unless you specify one of
the forms containing !.
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 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, the process blocks and you are notified (see JOBS
above.)
Diagnostic output may be directed through a pipe with the standard
output. Simply use the form |& instead of | to do this.
EXPRESSIONS
A number of the built-in commands take expressions that have operators
similar to those used for the C language, 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, 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 removes the need to use the
switch statement in shell scripts when all you need is pattern-matching.
csh interprets null or missing arguments as zero. The results of all
expressions are strings, which represent decimal numbers. Note that no
two components of an expression can appear in the same word. You should
surround them by spaces, except when they are adjacent to components of
expressions that are syntactically significant to the parser (&, |, <, >,
(, )).
Also available in expressions as primitive operands are command
executions enclosed in braces ({ and }), and file enquiries of the form
-l name where l is one of the following:
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 relationship to the real user.
If the file does not exist, or if it is inaccessible, all inquiries
return false (0). Command executions succeed, returning true (1), if the
command 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 non-seekable 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, it is executed in
a sub-shell.
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 cannot be alias or unalias.
alloc
Show the amount of dynamic memory acquired, broken down into used
and free memory. With an argument, this command shows the number of
free and used blocks in each size category. The categories start at
size eight and double at each step. This command's output may vary
across system types.
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. Thus you
can have multi-level breaks 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 you do
not specify an argument, 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 /, ./, or ../, check 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
/, 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 output, separated
by spaces, and terminated with a newline, unless you specify the -n
option.
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 generally 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
fg %job ...
Bring the current or specified jobs into the foreground, 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 prematurely. Use the
break command to terminate it prematurely. When the shell reads
this command from the terminal, it reads the loop once, prompting
with "? " before executing any statements in the loop. If you make
a mistake typing in a loop at the terminal, you can interrupt it.
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.
goto word
Perform filename- and command-expansion on the specified 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
component 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
Print the most recent events first (rather than printing the oldest
first).
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, execute the single
command with arguments. Variable substitution 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, in which case, command is not executed.
if (expr) then
...
else if (expr2) then
...
else
...
endif
If the specified expr is true, execute the commands to the first
else; otherwise if expr2 is true, execute the commands to the second
else, and so on. 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 lib
Install a user-supplied library specified by lib in the shell
process. The library is used to resolve external references of
programs (and libraries) loaded after its installation. Note that
the library is not loaded into the address space unless it is needed
to resolve an external reference. The list of inlibed libraries is
passed to all children of the current shell. Use llib(1) to examine
this list.
jobs List the active jobs.
jobs -l
List the active jobs, and include process IDs.
kill %job
kill -sig %job ...
kill pid
kill -sig pid ...
kill -l
Send either the TERM (terminate) signal or the specified signal to
the jobs or processes indicated. Provide 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
process for this command. If the signal being sent is TERM
(terminate) or HUP (hangup), the job or process is sent a CONT
(continue) signal as well.
limit
limit resource
limit resource maximum-use
limit -h
limit -h resource
limit -h resource maximum-use
Limits the consumption by the current process and each process it
creates, to not individually exceed maximum-use on the specified
resource. If you do not specify maximum-use, the current limit is
printed; if you do not specify resource, all limitations are given.
If you specify the -h flag, the hard limits are used instead of the
current limits. The hard limits impose a ceiling on the values of
the current limits. Only the super-user can raise the hard limits,
but a user can lower or raise the current limits within the legal
range.
Resources controllable currently include cputime (the maximum number
of CPU seconds to be used by each process), filesize (the largest
single file that you can create), datasize (the maximum growth of
the data region via sbrk(2) beyond the end of the program text),
stacksize (the size of the children's stack regions), and
coredumpsize (the size of the largest core dump that will be
created). NOTE: The coredumpsize limit is always 0 in Domain/OS.
You can specify the maximum-use as a (floating point or integer)
number followed by a scale factor. For all limits other than
cputime the default scale is `k' or `kilobytes' (1024 bytes); you
can also us a scale factor of `m' or `megabytes'. For cputime the
default scaling is `seconds', but you can specify `m' for minutes or
`h' for hours, or a time of the form `mm:ss' giving minutes and
seconds.
For both resource names and scale factors, unambiguous prefixes of
the names suffice.
login
Terminate a log-in shell, replacing it with an instance of
/bin/login. This is one way to log out, 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) scheduling priority for this shell to 4.
nice +number
Set the nice(1) priority to the given number.
nice command
Run command at nice(1) priority 4.
nice +number command
Run command at positive number nice(1) priority. The greater the
number, the lower CPU priority the process gets. The super-user can
specify negative priority by using nice -number .... The command is
always executed in a sub-shell, and the restrictions placed on
commands in simple if statements apply.
nohup
When you specify this command 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 &.
notify
notify %job ...
Notify the user asynchronously when the status of the current or
specified jobs changes (normally, notification 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 terminal 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
continue to be ignored by the shell and all invoked commands.
onintr -
Ignore all interrupts.
onintr label
Execute a goto label 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 working 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 be
necessary only if you add commands to one of your own directories,
or if someone changes the contents of one of the system directories.
repeat count command
Execute the specified command (subject to the same restrictions as
the command in the one-line if statement above) count times. I/O
redirections occur exactly once, even if count is zero.
rootnode arg
Change the current node entry directory to arg. See rootnode(1).
set Show the value of all shell variables. Variables that have other
than a single word as their value appear as a parenthesized word
list.
set name
Set name to the null string.
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 component 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. You can repeat these arguments
to set multiple values in a single set command. Note, however, that
variable expansion happens for all arguments before any setting
occurs.
setenv
List all current environment variables.
setenv name
Set name to an empty string.
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, discarding variable[1].
source name
Read commands from name. You may nest source commands, but if you
nest them too deeply, the shell may run out 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 background.
stop %job ...
Stop the specified job that is executing in the background.
suspend
Causes the shell to stop in its tracks, much as if it had been sent
a stop signal with CTRL/Z. This is most often used to stop shells
started by su(1)
switch (string)
case str1:
...
breaksw
...
default:
...
breaksw
endsw
Each case label is successively matched, against the specified
string which is first command and filename expanded. The file
metacharacters *, ? and [...] may be used in the case labels, which
are variable expanded. If none of the labels match before a
"default" label is found, then the execution begins after the
default label. Each case label and the default label must appear at
the beginning of a line. The command breaksw causes execution to
continue after the endsw. Otherwise control may fall through case
labels and default labels as in C. If no label matches and there is
no default, execution continues after the endsw.
time Print a summary of time used by this shell and its children.
time command
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.
umask
Display the file-creation mask (in octal).
umask value
Set the file-creation mask to the specified value. Common values for
the mask are 002 (giving all access to the group and read and
execute access to others) or 022 (giving all except write access to
users in the group or others).
unalias pattern
Discard all aliases whose names match the specified pattern. Thus,
unalias * removes all aliases. 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.
unlimit
unlimit resource
unlimit -h
unlimit -h resource
Removes the limitation on resource. If you do not specify resource,
all resource limitations are removed. If you specify -h, the
corresponding hard limits are removed. Only the super-user can do
this.
unset pattern
Remove all variables whose names match the specified pattern. Thus,
unset * removes all variables. 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) command.
ver systype [ command ]
With no arguments, return the current value of the SYSTYPE
environment variable. With a systype argument, change the SYSTYPE
environment variable to either bsd4.3 or sys5.3, depending on which
is specified.
wait Wait for all background jobs. If the shell is interactive, an
interrupt can disrupt the wait, and the shell prints the names and
job numbers of all jobs known to be outstanding.
which
Identify which file would be executed if the command were submitted
for execution. The command is submitted to normal alias and
variable substitutions.
while (expr)
...
end While the specified expression evaluates to nonzero, evaluate the
commands between the while and the matching end. You can use break
and continue to terminate or continue the loop prematurely. (The
while and end must appear alone on their input lines.) Prompting
occurs the first time through the loop, as for the foreach statement
if the input is a terminal.
%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 >, <, &, or | character, you must enclose at least that
part in parentheses.
@ name[index] = expr
Assign the value of expr to the indexth argument of name. Both name
and its indexth component must already exist.
The operators *=, +=, etc., are available as in C. The space
separating the name from the assignment operator is optional.
However, spaces are mandatory in separating components of expr that
would otherwise be single words. Special postfix ++ and --
operators increment and decrement name, respectively, for example, @
i++.
PREDEFINED AND ENVIRONMENT VARIABLES
The following variables have special meaning to csh. Of these, the shell
sets argv, cwd, home, path, prompt, shell, and status. 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 variable; TERM
into term; and HOME into home. It then copies these back into the
environment whenever the normal shell variables are reset.
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 definition 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, that
is, $argv[1] replaces $1, etc.
cdpath Give a list of alternate directories searched to find
subdirectories in chdir commands.
cwd Give the full pathname of the current directory.
echo Echo each command and its arguments just before the
command is executed. This variable is set when you
specify the -x command line option. 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.
filec Enable filename completion.
histchars Change the characters used in history substitution, if you
specify a string value. Use the first character of its
value as the history substitution character, replacing the
default character !. The second character of its value
replaces the ^ character in quick substitutions.
history Control the size of the history list. If you specify a
numeric value, do not discard any command that has been
referenced in that many events. The last executed command
is always saved 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 of ~ refers
to this variable.
ignoreeof If set, ignore the end-of-file from terminal input
devices. This prevents shells from accidentally being
killed by an EOF.
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 tells you that you have new mail in
name, when there is mail in the file name.
noclobber Restrict output redirection to ensure that files are not
accidentally destroyed, and that redirections done with >>
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 filename,s and further expansions are
not desirable.
nonomatch If set, it is not an error for a filename expansion not to
match any existing files; rather, the primitive pattern is
returned. It is still an error for the primitive pattern
to be malformed, that is, echo [ still gives an error.
notify If set, notify the user asynchronously of job completions.
By default, the shell presents job completions just before
printing a prompt.
path Each word of the path variable specifies a directory in
which commands are to be sought for execution. A null
word specifies the current directory. If there is no path
variable, csh executes only full pathnames. The default
search path in Domain/OS SysV is (. /usr/ucb /bin /usr/bin
/usr/apollo/bin). However, this may vary from system to
system. For the super-user, the default search path is
(/etc /bin /usr/bin /usr/apollo/bin), which may also vary.
A shell that is given neither the -c nor the -t option
normally hashes the contents of the directories in the
path variable after reading .cshrc, and each time the path
variable is reset. If new commands are added to these
directories while the shell is active, it may be necessary
to give the rehash comand, or the new commands may not be
found.
prompt The string printed on the csh command line, before the
shell reads commands from an interactive terminal input.
If ! appears in the string, replace it by the current
event number (unless a preceding backslash is given). The
default prompt is "%"; for the super-user, the default
prompt is "#".
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 the
history list, enabling history to be saved across log-ins.
If the value of savehist is too large, the shell is 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.
(See the description of Non-Built-in Command Execution,
below.) 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 128 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, a
utilization percentage, and real times for any command
that takes more than this many CPU seconds, when the
command terminates. A utilization percentage is the ratio
of user time plus system time to real time.
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 you do not specify either a -c or a -t option,
the shell hashes the names in these directories into an internal table so
that it tries an exec in a directory only if the command potentially
resides there. This greatly speeds command location when a lot of
directories are present in the search path. For each directory component
of path that does not begin with a /, the shell concatenates with the
given command name to form a pathname of a file that it then attempts to
execute. The shell also does this if the internal hash table mechanism
is turned off (via unhash), or a -c or -t command-line option is
specified in csh.
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 directory. 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, and spawns
a new shell to read it.
If there is an alias for shell, the words of the alias are prefixed to
the argument list to form the shell command. The first word of the alias
should be the full pathname of the shell (for example, $shell). Note
that this is a special, late-occurring, case of alias substitution, and
it only allows words to be prefixed to the argument list without
modification.
COMMAND LINE OPTIONS
-b This flag forces a break from option processing, causing any further
shell arguments to be treated as non-option arguments. The
remaining arguments are not interpreted as shell options. You can
use the -b to pass options to a shell script without confusion or
possible subterfuge. The shell will not run a set-user ID script
without this option.
-c Commands are read from the (single) following argument, which must
be present. Any remaining arguments are placed in argv.
-Dname=value
Set the parameter name to value, then pass it to the shell's
environment. This option is useful for tailoring the environment of
a shell invoked from a program that isn't a shell (such as the DM).
For example, if your key definition sets the -D variable as follows:
kd cp /bin/csh -DNEWPAD=true ke, the .cshrc script can use the value
of the NEWPAD variable to execute additional commands or perform
special processing. You can specify a number of -D options.
-e The shell exits if any invoked command terminates abnormally or
yields a nonzero exit status.
-f The shell starts faster, because it neither searches for nor
executes commands from the file .cshrc in the invoker's home
directory.
-i The shell is interactive and prompts for its top-level input, even
if it appears not to be a terminal. Shells are interactive without
this option if their inputs and outputs are terminals.
-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. Use a backslash (\) 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.
-x Set the echo variable, so that commands are echoed immediately
before execution.
-V Set the verbose variable even before .cshrc is executed.
-X Set the echo variable even before .cshrc is executed.
ARGUMENT LIST PROCESSING
If argument 0 to the shell starts with a dash (-), this is a log-in
shell. If arguments remain after command-line options are processed, but
you did not specify one of the -c, -i, -s, or -t options, 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 version 7
shells whose shell scripts are not compatible with this shell, csh
executes a standard shell if the first character of a script is not a
pound sign (#), that is, if the script does not start with a comment.
Remaining arguments initialize the argv variable.
SIGNAL HANDLING
csh normally ignores quit signals. Jobs running detached, either by &,
or the bg or %... & commands, are immune to signals generated from the
keyboard, including hangups. Other signals have the values the shell
inherited from its parent. Use onintr. to control the shell's handling
of interrupts and terminate signals in shell scripts. 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
interrupts allowed when a log-in shell is reading the file .logout.
LIMITATIONS
Words can be no longer than 1024 characters. The system limits argument
lists to 10240 characters. The number of arguments to a command that
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 single line to 20.
WARNINGS
csh will not read .cshrc or .login if the files are owned by another
user.
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.
Shell built-in functions are not stoppable/restartable. Command
sequences of the form `a ; b ; c' are also not handled 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. It suffices to enclose the sequence of commands in
parentheses to force it to a subshell, for example, `( a ; b ; c )'.
Control over tty output after processes are started is primitive; perhaps
this will inspire someone to work on a good virtual terminal interface.
In a virtual terminal interface much more interesting things could be
done with output control.
Alias substitution is most often used to clumsily simulate shell
procedures; you should use shell procedures rather than aliases.
Commands within loops, prompted for by "?", are not placed in the history
list. Control structure should be parsed rather than 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. All and more than one : modifier should be allowed on $
substitutions.
The way the filec facility is implemented is ugly and expensive.
The built-in time function correctly calculates user time, system time,
elapsed time, and utilization percentages. The number of input and
output requests, page faults, dirty pages, reclaimed pages, as well as
the amount of shared/unshared/total memory may be calculated in error.
In most cases, the data displayed is simply 0.
FILES
~/.cshrc Read at beginning of execution by each shell.
~/.login Read by log-in shell, after .cshrc at login.
~/.logout Read by log-in shell, at logout.
/bin/sh Standard shell, for shell scripts not starting with a `#'.
/tmp/sh* Temporary file for `<<'.
/etc/passwd Source of home directories for `~name'.
SEE ALSO
sh(1), access(2), execve(2), fork(2), pipe(2), umask(2), wait(2), tty(4),
a.out(5), environ(7);
Using Your SysV Environment.