features of other shells which make writing shell programs (shell
scripts) easier, most of the features unique to are designed more
for the interactive UNIX user.  UNIX users who have read a gener-
al introduction to the system will find a valuable basic explana-
tion of the shell here.  Simple terminal interaction with is pos-
sible after reading just the first section of this document.  The
second  section  describes the shell's capabilities which you can
explore after you have begun to become acquainted with the shell.
Later  sections introduce features which are useful, but not nec-
essary for all users of the shell.   Additional  information  in-
cludes  an appendix listing special characters of the shell and a
glossary of terms and commands introduced in this manual.  Intro-
duction  A is a command language interpreter.  is the name of one
particular command interpreter on UNIX.  The primary  purpose  of
is to translate command lines typed at a terminal into system ac-
tions, such as invocation of other programs.  is a  user  program
just  like any you might write.  Hopefully, will be a very useful
program for you in interacting with the UNIX system.  In addition
to  this  document,  you will want to refer to a copy of the UNIX
User Reference Manual.  The documentation in  section  1  of  the
manual  provides  a full description of all features of the shell
and is the definitive reference for questions  about  the  shell.
Many  words  in  this  document  are shown in These are important
words; names of commands, and words which have special meaning in
discussing  the shell and UNIX.  Many of the words are defined in
a glossary at the end of this document.  If you don't  know  what
is  meant by a word, you should look for it in the glossary.  Ac-
knowledgements Numerous people have  provided  good  input  about
previous versions of and aided in its debugging and in the debug-
ging of its documentation.  I  would  especially  like  to  thank
Michael  Ubell who made the crucial observation that history com-
mands could be done well over the word structure of  input  text,
and implemented a prototype history mechanism in an older version
of the shell.  Eric Allman has also provided a  large  number  of
useful  comments  on  the  shell, helping to unify those concepts
which are present and  to  identify  and  eliminate  useless  and
marginally  useful features.  Mike O'Brien suggested the pathname
hashing mechanism which speeds command execution.  Jim Kulp added
the  job  control  and directory stack primitives and added their
documentation to this introduction.












as  a  mechanism for invoking other programs.  in the UNIX system
consist of a list of strings or interpreted as a followed by Thus
the  command  mail  bill  consists  of two words.  The first word
names the command to be executed, in this case the  mail  program
which  sends messages to other users.  The shell uses the name of
the command in attempting to execute it for you.  It will look in
a number of for a file with the name which is expected to contain
the mail program.  The rest of the words of the command are given
as  to  the  command itself when it is executed.  In this case we
specified also the argument which is interpreted by  the  program
to  be  the name of a user to whom mail is to be sent.  In normal
terminal usage we might use the command as follows.  % mail  bill
I have a question about the csh documentation.  My document seems
to be missing page 5.  Does a page five exist?          Bill  EOT
%  Here we typed a message to send to and ended this message with
a ^D which sent an end-of-file to the mail  program.   (Here  and
throughout  this  document,  the  notation  ``^x''  is to be read
``control-x'' and represents the striking of the x key while  the
control  key  is  held  down.)   The mail program then echoed the
characters `EOT' and transmitted our message.  The characters  `%
'  were printed before and after the mail command by the shell to
indicate that input was needed.  After typing the `% ' prompt the
shell  was  reading  command input from our terminal.  We typed a
complete command `mail bill'.  The shell then executed  the  pro-
gram  with  argument and went dormant waiting for it to complete.
The mail program then read input from our terminal until we  sig-
nalled  an  end-of-file via typing a ^D after which the shell no-
ticed that mail had completed and signaled us that it  was  ready
to  read from the terminal again by printing another `% ' prompt.
This is the  essential  pattern  of  all  interaction  with  UNIX
through  the shell.  A complete command is typed at the terminal,
the shell executes the command and when this execution completes,
it prompts for a new command.  If you run the editor for an hour,
the shell will patiently wait for you to finish editing and  obe-
diently prompt you again whenever you finish editing.  An example
of a useful command you can execute now  is  the  command,  which
sets  the  default  and  characters  on your terminal - the erase
character erases the last character you typed and the kill  char-
acter  erases  the  entire  line you have entered so far.  By de-
fault, the erase character is the delete key (equivalent to `^?')
and  the  kill character is `^U'.  Some people prefer to make the
erase character the backspace key (equivalent to `^H').  You  can
make  this  be  true by typing tset -e which tells the program to
set the erase character to tset's default setting for this  char-
acter  (a  backspace).  Flag arguments A useful notion in UNIX is
that of a argument.  While many  arguments  to  commands  specify
file  names  or  user names, some arguments rather specify an op-
tional capability of the command which you wish  to  invoke.   By
convention, such arguments begin with the character `-' (hyphen).
Thus the command ls will produce a list of the files in the  cur-
rent  The  option  is  the  size option, and ls -s causes to also
give, for each file the size of the file in blocks of 512 charac-
mand  through  a  notation using the `>' and the name of the file
where output is to be placed.  Thus the command date >  now  runs
the  command  such  that  its  standard  output is the file `now'
rather than the terminal.  Thus this command places  the  current
date  and time into the file `now'.  It is important to know that
the command was unaware that its  output  was  going  to  a  file
rather than to the terminal.  The shell performed this before the
command began executing.  One other thing to note  here  is  that
the  file `now' need not have existed before the command was exe-
cuted; the shell would have created the file if it did not exist.
And  if  the  file did exist?  If it had existed previously these
previous contents would have been discarded!  A shell option  ex-
ists to prevent this from happening accidentally; it is discussed
in section 2.2.  The system normally keeps files which you create
with  `>'  and all other files.  Thus the default is for files to
be permanent.  If you wish to create a file which will be removed
automatically,  you can begin its name with a `#' character, this
`scratch' character denotes the fact that  the  file  will  be  a
scratch  file.*  *Note that if your erase character is a `#', you
will have to precede the `#' with a `\'.  The fact that  the  `#'
character  is  the  old  (pre-CRT) standard erase character means
that it seldom appears in a file name, and allows this convention
to be used for scratch files.  If you are using a CRT, your erase
character should be a ^H, as we demonstrated in section  1.1  how
this  could be set up.  The system will remove such files after a
couple of days, or sooner  if  file  space  becomes  very  tight.
Thus,  in running the command above, we don't really want to save
the output forever, so we  would  more  likely  do  date  >  #now
Metacharacters  in the shell The shell has a large number of spe-
cial characters (like `>') which indicate special functions.   We
say  that these notations have and meaning to the shell.  In gen-
eral, most characters which are neither letters nor  digits  have
special  meaning to the shell.  We shall shortly learn a means of
which allows us to use without the shell  treating  them  in  any
special  way.   Metacharacters normally have effect only when the
shell is reading our input.  We  need  not  worry  about  placing
shell  metacharacters  in  a letter we are sending via or when we
are typing in text or data to some other program.  Note that  the
shell  is  only reading input when it has prompted with `% ' (al-
though we can type our input even before it prompts).  Input from
files;  pipelines  We  learned above how to the of a command to a
file.  It is also possible to redirect the of a  command  from  a
file.   This is not often necessary since most commands will read
from a file whose name is given as an argument.  We can give  the
command sort < data to run the command with standard input, where
the command normally reads its input, from the file  `data'.   We
would more likely say sort data letting the command open the file
`data' for input itself since this is less to  type.   We  should
note  that if we just typed sort then the sort program would sort
lines from its Since we did not the standard input, it would sort
lines as we typed them on the terminal until we typed a ^D to in-
dicate an end-of-file.  A most useful capability is  the  ability
a  sorted list of our files by size, but with the smallest first.
We could then use the reverse sort option and the command in com-
bination  with  the  previous  command doing ls -s | sort -n -r |
head -5 Here we have taken a list of our files sorted  alphabeti-
cally,  each  with  the  size in blocks.  We have run this to the
standard input of the command asking it to  sort  numerically  in
reverse order (largest first).  This output has then been run in-
to the command which gives us the first few lines.  In this  case
we  have asked for the first 5 lines.  Thus this command gives us
the names and sizes of our 5 largest files.  The notation  intro-
duced  above  is called the mechanism.  Commands separated by `|'
characters are connected together by the shell and  the  standard
output  of  each is run into the standard input of the next.  The
leftmost command in a pipeline will normally  take  its  standard
input from the terminal and the rightmost will place its standard
output on the terminal.  Other examples of pipelines will be giv-
en later when we discuss the history mechanism; one important use
of pipes which is illustrated there is in the routing of informa-
tion to the line printer.  Filenames Many commands to be executed
will need the names of files as arguments.   UNIX  consist  of  a
number of separated by `/'.  Each component except the last names
a directory in which the next component resides, in effect speci-
fying  the  of directories to follow to reach the file.  Thus the
pathname /etc/motd specifies a file in the directory `etc'  which
is  a  subdirectory  of the directory `/'.  Within this directory
the file named is `motd' which stands for `message of  the  day'.
A  that begins with a slash is said to be an pathname since it is
specified from the absolute top of the entire directory hierarchy
of the system (the which do not begin with `/' are interpreted as
starting in the current which is, by default, your directory  and
can be changed dynamically by the change directory command.  Such
pathnames are said to be to the working directory since they  are
found by starting in the working directory and descending to low-
er levels of directories for each of the pathname.  If the  path-
name contains no slashes at all then the file is contained in the
working directory itself and the pathname is merely the  name  of
the  file in this directory.  Absolute pathnames have no relation
to the working directory.  Most filenames consist of a number  of
alphanumeric  characters and `.'s (periods).  In fact, all print-
ing characters except `/' (slash) may appear in filenames.  It is
inconvenient  to have most non-alphabetic characters in filenames
because many of these have special meaning  to  the  shell.   The
character  `.' (period) is not a shell-metacharacter and is often
used to separate the of a file name from the base  of  the  name.
Thus  prog.c prog.o prog.errs prog.output are four related files.
They share a portion of a name (a base portion being that part of
the  name  that is left when a trailing `.' and following charac-
ters which are not `.' are  stripped  off).   The  file  `prog.c'
might be the source for a C program, the file `prog.o' the corre-
sponding object file, the file `prog.errs' the  errors  resulting
from  a compilation of the program and the file `prog.output' the
output of a run of the program.  If we wished  to  refer  to  all
filenames;  first those with one character names, then those with
two character names,  and  finally  those  with  three  character
names.   The  names  of each length will be independently sorted.
Another mechanism consists of a sequence  of  characters  between
`[' and `]'.  This metasequence matches any single character from
the enclosed set.  Thus prog.[co] will match prog.c prog.o in the
example  above.  We can also place two characters around a `-' in
this notation to denote a range.   Thus  chap.[1-5]  might  match
files  chap.1  chap.2 chap.3 chap.4 chap.5 if they existed.  This
is shorthand for chap.[12345] and otherwise equivalent.   An  im-
portant  point  to  note is that if a list of argument words to a
command (an contains filename expansion syntax, and if this file-
name  expansion  syntax  fails  to match any existing file names,
then the shell considers this to be an error and prints  a  diag-
nostic No match.  and does not execute the command.  Another very
important point is that files with the character `.' at  the  be-
ginning are treated specially.  Neither `*' or `?' or the `[' `]'
mechanism will match it.  This prevents  accidental  matching  of
the  filenames  `.' and `..'  in the working directory which have
special meaning to the system, as well as  other  files  such  as
which are not normally visible.  We will discuss the special role
of the file later.  Another filename  expansion  mechanism  gives
access to the pathname of the directory of other users.  This no-
tation consists of the character `~' (tilde) followed by  another
user's  login  name.   For instance the word `~bill' would map to
the pathname `/usr/bill' if the home  directory  for  `bill'  was
`/usr/bill'.   Since,  on large systems, users may have login di-
rectories scattered over many different disk volumes with differ-
ent  prefix  directory names, this notation provides a convenient
way of accessing the files of other users.   A  special  case  of
this notation consists of a `~' alone, e.g. `~/mbox'.  This nota-
tion is expanded by the shell into the file `mbox' in your direc-
tory,  i.e. into `/usr/bill/mbox' for me on Ernie Co-vax, the UCB
Computer Science Department VAX machine, where this document  was
prepared.   This can be very useful if you have used to change to
another directory and have found a file you wish to copy using If
I  give the command cp thatfile ~ the shell will expand this com-
mand  to  cp  thatfile  /usr/bill  since  my  home  directory  is
/usr/bill.   There  also  exists a mechanism using the characters
`{' and `}' for abbreviating a set of  words  which  have  common
parts  but  cannot be abbreviated by the above mechanisms because
they are not files, are the names of files which do not  yet  ex-
ist, are not thus conveniently described.  This mechanism will be
described much later, in section 4.2, as it  is  used  less  fre-
quently.   Quotation We have already seen a number of metacharac-
ters used by the shell.  These metacharacters pose a  problem  in
that  we  cannot  use  them directly as parts of words.  Thus the
command echo * will not echo the character `*'.  It  will  either
echo  a sorted list of filenames in the current or print the mes-
sage `No match' if there are no files in the  working  directory.
The  recommended  mechanism for placing characters which are nei-
ther numbers, digits, `/', `.' or `-' in an argument  word  to  a
likely  to  continue for several minutes unless you stop it.  You
can send an INTERRUPT to the command by typing ^C on your  termi-
nal.*   *On some older Unix systems the DEL or RUBOUT key has the
same effect. "stty all" will tell you the INTR key value.   Since
does  not  take any precautions to avoid or otherwise handle this
signal the INTERRUPT will cause it to terminate.  The  shell  no-
tices  that  has  terminated and prompts you again with `% '.  If
you hit INTERRUPT again, the shell will just  repeat  its  prompt
since it handles INTERRUPT signals and chooses to continue to ex-
ecute commands rather than terminating like did, which would have
the  effect  of  logging you out.  Another way in which many pro-
grams terminate is when they get an end-of-file from their  stan-
dard input.  Thus the program in the first example above was ter-
minated when we typed a ^D which generates  an  end-of-file  from
the  standard  input.   The shell also terminates when it gets an
end-of-file printing `logout'; UNIX then logs you off the system.
Since  this  means that typing too many ^D's can accidentally log
us off, the shell has a mechanism for preventing this.  This  op-
tion  will  be  discussed  in  section 2.2.  If a command has its
standard input redirected from a file, then it will normally ter-
minate  when it reaches the end of this file.  Thus if we execute
mail bill < prepared.text the mail command will terminate without
our  typing  a ^D.  This is because it read to the end-of-file of
our file `prepared.text' in which we placed a message for  `bill'
with  an  editor  program.   We  could  also  have  done cat pre-
pared.text | mail bill since the command would then have  written
the  text through the pipe to the standard input of the mail com-
mand.  When the command completed it would have terminated, clos-
ing down the pipeline and the command would have received an end-
of-file from it and terminated.  Using a pipe here is  more  com-
plicated  than  redirecting input so we would more likely use the
first form.  These commands could also have been stopped by send-
ing  an INTERRUPT.  Another possibility for stopping a command is
to suspend its execution temporarily,  with  the  possibility  of
continuing  execution later.  This is done by sending a STOP sig-
nal via typing a ^Z.  This signal causes all commands running  on
the terminal (usually one but more if a pipeline is executing) to
become suspended.  The shell notices  that  the  command(s)  have
been  suspended,  types `Stopped' and then prompts for a new com-
mand.  The previously executing command has been  suspended,  but
otherwise  unaffected by the STOP signal.  Any other commands can
be executed while the original command  remains  suspended.   The
suspended  command can be continued using the command with no ar-
guments.  The shell will then retype the command  to  remind  you
which command is being continued, and cause the command to resume
execution.  Unless any input files in use by the  suspended  com-
mand have been changed in the meantime, the suspension has no ef-
fect whatsoever on the execution of the  command.   This  feature
can  be  very useful during editing, when you need to look at an-
other file before continuing.  An example of  command  suspension
follows.   %  mail  harold Someone just copied a big file into my
directory and its name is ^Z Stopped % ls funnyfile prog.c prog.o
sent from the keyboard.  This also happens on INTERRUPT, and QUIT
signals.  More information on  suspending  jobs  and  controlling
them is given in section 2.6.  If you write or run programs which
are not fully debugged then it may  be  necessary  to  stop  them
somewhat  ungracefully.   This can be done by sending them a QUIT
signal, sent by typing a ^\.  This will usually provoke the shell
to  produce  a message like: Quit (Core dumped) indicating that a
file `core' has been created  containing  information  about  the
running  program's  state when it terminated due to the QUIT sig-
nal.  You can examine this file yourself, or forward  information
to  the  maintainer  of the program telling him/her where the is.
If you run background commands (as explained in section 2.6) then
these commands will ignore INTERRUPT and QUIT signals at the ter-
minal.  To stop them you must use the command.  See  section  2.6
for  an  example.  If you want to examine the output of a command
without having it move off the screen as the output  of  the  cat
/etc/passwd command will, you can use the command more /etc/pass-
wd The program pauses after each  complete  screenful  and  types
`--More--'  at  which  point  you  can hit a space to get another
screenful, a return to get another line, a `?' to get  some  help
on other commands, or a `q' to end the program.  You can also use
more as a filter, i.e.  cat /etc/passwd | more  works  just  like
the  more simple more command above.  For stopping output of com-
mands not involving you can use the ^S key to stop  the  typeout.
The  typeout will resume when you hit ^Q or any other key, but ^Q
is normally used because it only restarts the output and does not
become input to the program which is running.  This works well on
low-speed terminals, but at 9600 baud it is hard to type  ^S  and
^Q  fast enough to paginate the output nicely, and a program like
is usually used.  An additional possibility  is  to  use  the  ^O
flush  output character; when this character is typed, all output
from the current command is thrown away (quickly) until the  next
input  read  occurs  or until the next shell prompt.  This can be
used to allow a command to  complete  without  having  to  suffer
through  the output on a slow terminal; ^O is a toggle, so flush-
ing can be turned off by typing ^O again while  output  is  being
flushed.   What  now?  We have so far seen a number of mechanisms
of the shell and learned a lot about the way in  which  it  oper-
ates.  The remaining sections will go yet further into the inter-
nals of the shell, but you will surely  want  to  try  using  the
shell  before  you  go  any further.  To try it you can log in to
UNIX and type the following command to the  system:  chsh  myname
/bin/csh  Here  `myname' should be replaced by the name you typed
to the system prompt of `login:' to get onto the system.  Thus  I
would  use  `chsh bill /bin/csh'.  You only have to do this once;
it takes effect at next login.  You are now ready  to  try  using
Before  you  do  the `chsh' command, the shell you are using when
you log into the system is `/bin/sh'.  In fact, much of the above
discussion is applicable to `/bin/sh'.  The next section will in-
troduce many features particular to so  you  should  change  your
shell to before you begin reading it.