1 .\" Copyright (c) 1980, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" @(#)csh.1 8.1 (Berkeley) 6/8/93
33 .\" $FreeBSD: src/bin/csh/USD.doc/csh.1,v 1.9.2.2 2003/01/24 02:12:02 keramida Exp $
35 .EH 'USD:4-%''An Introduction to the C shell'
36 .OH 'An Introduction to the C shell''USD:4-%'
39 An Introduction to the C shell
42 (revised for 4.3BSD by Mark Seiden)
44 Computer Science Division
46 Department of Electrical Engineering and Computer Science
48 University of California, Berkeley
50 Berkeley, California 94720
53 is a new command language interpreter for
56 It incorporates good features of other shells and a
58 mechanism similar to the
61 While incorporating many features of other shells which make
62 writing shell programs (shell scripts) easier,
63 most of the features unique to
65 are designed more for the interactive \s-2UNIX\s0 user.
68 users who have read a general introduction to the system
69 will find a valuable basic explanation of the shell here.
70 Simple terminal interaction with
72 is possible after reading just the first section of this document.
73 The second section describes the shell's capabilities which you can
74 explore after you have begun to become acquainted with the shell.
75 Later sections introduce features which are useful, but not necessary
76 for all users of the shell.
78 Additional information includes an appendix listing special characters of the shell
79 and a glossary of terms and commands introduced in this manual.
87 is a command language interpreter.
89 is the name of one particular command interpreter on
91 The primary purpose of
93 is to translate command lines typed at a terminal into
94 system actions, such as invocation of other programs.
96 is a user program just like any you might write.
99 will be a very useful program for you
100 in interacting with the \s-2UNIX\s0 system.
102 In addition to this document, you will want to refer to a copy
103 of the \s-2UNIX\s0 User Reference Manual.
106 documentation in section 1 of the manual provides a full description of all
107 features of the shell and is the definitive reference for questions
110 Many words in this document are shown in
112 These are important words;
113 names of commands, and words which have special meaning in discussing
114 the shell and \s-2UNIX\s0.
115 Many of the words are defined in a glossary at the end of this document.
116 If you don't know what is meant by a word, you should look
117 for it in the glossary.
121 Numerous people have provided good input about previous versions
124 and aided in its debugging and in the debugging of its documentation.
125 I would especially like to thank Michael Ubell
126 who made the crucial observation that history commands could be
127 done well over the word structure of input text, and implemented
128 a prototype history mechanism in an older version of the shell.
129 Eric Allman has also provided a large number of useful comments on the
130 shell, helping to unify those concepts which are present and to identify
131 and eliminate useless and marginally useful features.
132 Mike O'Brien suggested the pathname hashing
133 mechanism which speeds command execution.
134 Jim Kulp added the job control and directory stack primitives and
135 added their documentation to this introduction.
139 Terminal usage of the shell
141 The basic notion of commands
147 acts mostly as a medium through which other
150 While it has a set of
152 functions which it performs directly,
153 most commands cause execution of programs that are, in fact,
154 external to the shell.
155 The shell is thus distinguished from the command interpreters of other
156 systems both by the fact that it is just a user program, and by the fact
157 that it is used almost exclusively as a mechanism for invoking other programs.
160 in the \s-2UNIX\s0 system consist of a list of strings or
170 consists of two words.
173 names the command to be executed, in this case the
174 mail program which sends messages to other users.
175 The shell uses the name of the command in attempting to execute it for you.
176 It will look in a number of
178 for a file with the name
180 which is expected to contain the mail program.
182 The rest of the words of the command are given as
184 to the command itself when it is executed.
185 In this case we specified also the argument
187 which is interpreted by the
189 program to be the name of a user to whom mail is to be sent.
190 In normal terminal usage we might use the
195 I have a question about the csh documentation.
196 My document seems to be missing page 5.
197 Does a page five exist?
203 Here we typed a message to send to
205 and ended this message with a ^D which sent an end-of-file to
207 (Here and throughout this document, the notation ``^\fIx\fR''
208 is to be read ``control-\fIx\fR'' and represents the striking of the \fIx\fR
209 key while the control key is held down.)
211 then echoed the characters `EOT' and transmitted our message.
212 The characters `% ' were printed before and after the mail command
213 by the shell to indicate that input was needed.
215 After typing the `% ' prompt the shell was reading command input from
217 We typed a complete command `mail bill'.
218 The shell then executed the
220 program with argument
222 and went dormant waiting for it to complete.
223 The mail program then read input from our terminal until we signalled
224 an end-of-file via typing a ^D after which the shell noticed
225 that mail had completed
226 and signaled us that it was ready to read from the terminal again by
227 printing another `% ' prompt.
229 This is the essential pattern of all interaction with \s-2UNIX\s0
231 A complete command is typed at the terminal, the shell executes
232 the command and when this execution completes, it prompts for a new command.
233 If you run the editor for an hour, the shell will patiently wait for
234 you to finish editing and obediently prompt you again whenever you finish
237 An example of a useful command you can execute now is the
239 command, which sets the default
243 characters on your terminal \- the erase character erases the last
244 character you typed and the kill character erases the entire line you
246 By default, the erase character is the delete key (equivalent to `^?')
247 and the kill character is `^U'. Some people prefer to make the erase character
248 the backspace key (equivalent to `^H').
249 You can make this be true by typing
253 which tells the program
255 to set the erase character to tset's default setting for this character
260 A useful notion in \s-2UNIX\s0 is that of a
263 While many arguments to commands specify file names or user names,
264 some arguments rather specify an optional capability of the command
265 which you wish to invoke.
266 By convention, such arguments begin with the character `\-' (hyphen).
271 will produce a list of the files in the current
272 .I "working directory" .
275 is the size option, and
281 to also give, for each file the size of the file in blocks of 512
283 The manual section for each command in the \s-2UNIX\s0 reference manual
284 gives the available options for each command.
287 command has a large number of useful and interesting options.
288 Most other commands have either no options or only one or two options.
289 It is hard to remember options of commands which are not used very
290 frequently, so most \s-2UNIX\s0 utilities perform only one or two functions
291 rather than having a large number of hard to remember options.
295 Commands that normally read input or write output on the terminal
296 can also be executed with this input and/or output done to
299 Thus suppose we wish to save the current date in a file called `now'.
304 will print the current date on our terminal.
305 This is because our terminal is the default
307 for the date command and the date command prints the date on its
313 of a command through a
316 `>' and the name of the file where output is to be placed.
323 command such that its standard output is
324 the file `now' rather than the terminal.
325 Thus this command places the current date and time into the file `now'.
326 It is important to know that the
328 command was unaware that its output was going to a file rather than
330 The shell performed this
332 before the command began executing.
334 One other thing to note here is that the file `now'
335 need not have existed before the
337 command was executed; the shell would have created the file if it did
339 And if the file did exist?
340 If it had existed previously these previous contents would have been discarded!
343 exists to prevent this from happening accidentally;
344 it is discussed in section 2.2.
346 The system normally keeps files which you create with `>' and all other files.
347 Thus the default is for files to be permanent. If you wish to create a file
348 which will be removed automatically, you can begin its name with a `#'
349 character, this `scratch' character denotes the fact that the file will
352 *Note that if your erase character is a `#', you will have to precede the
353 `#' with a `\e'. The fact that the `#' character is the old (pre-\s-2CRT\s0)
354 standard erase character means that it seldom appears in a file name, and
355 allows this convention to be used for scratch files. If you are using a
356 \s-2CRT\s0, your erase character should be a ^H, as we demonstrated
357 in section 1.1 how this could be set up.
359 The system will remove such files after a couple of days,
360 or sooner if file space becomes very tight.
363 command above, we don't really want to save the output forever, so we
369 Metacharacters in the shell
371 The shell has a large number of
372 special characters (like `>')
373 which indicate special functions.
374 We say that these notations have
378 meaning to the shell.
379 In general, most characters which are neither letters nor digits
380 have special meaning to the shell.
381 We shall shortly learn a means of
383 which allows us to use
385 without the shell treating them in any special way.
387 Metacharacters normally have effect only when the shell is reading
389 We need not worry about placing shell metacharacters in a letter
392 or when we are typing in text or data to some other program.
393 Note that the shell is only reading input when it has prompted with
394 `% ' (although we can type our input even before it prompts).
396 Input from files; pipelines
398 We learned above how to
404 It is also possible to redirect the
406 of a command from a file.
407 This is not often necessary since most commands will read from
408 a file whose name is given as an argument.
409 We can give the command
415 command with standard input, where the command normally
416 reads its input, from the file
418 We would more likely say
424 command open the file
426 for input itself since this is less to type.
428 We should note that if we just typed
432 then the sort program would sort lines from its
436 the standard input, it would sort lines as we typed them on the terminal
437 until we typed a ^D to indicate an end-of-file.
439 A most useful capability is the ability to combine the standard output
440 of one command with the standard input of another, i.e. to run the
441 commands in a sequence known as a
443 For instance the command
447 normally produces a list of the files in our directory with the size
448 of each in blocks of 512 characters.
449 If we are interested in learning which of our files is largest we
450 may wish to have this sorted by size rather than by name, which is
451 the default way in which
454 We could look at the many options of
456 to see if there was an option to do this but would eventually discover
458 Instead we can use a couple of simple options of the
460 command, combining it with
466 option of sort specifies a numeric sort rather than an alphabetic sort.
471 specifies that the output of the
473 command run with the option
479 run with the numeric sort option.
480 This would give us a sorted list of our files by size, but with the
482 We could then use the
484 reverse sort option and the
486 command in combination with the previous command doing
488 ls \-s | sort \-n \-r | head \-5
490 Here we have taken a list of our files sorted alphabetically,
491 each with the size in blocks.
492 We have run this to the standard input of the
494 command asking it to sort numerically in reverse order (largest first).
495 This output has then been run into the command
497 which gives us the first few lines.
498 In this case we have asked
500 for the first 5 lines.
501 Thus this command gives us the names and sizes of our 5 largest files.
503 The notation introduced above is called the
506 Commands separated by `\||\|' characters are connected together by the
507 shell and the standard output of each is run into the standard input of the
509 The leftmost command in a pipeline will normally take its standard
510 input from the terminal and the rightmost will place its standard
511 output on the terminal.
512 Other examples of pipelines will be given later when we discuss the
514 one important use of pipes which is illustrated there is in the
515 routing of information to the line printer.
519 Many commands to be executed will need the names of files as arguments.
522 consist of a number of
525 Each component except the last names a directory in which the next
526 component resides, in effect specifying the
528 of directories to follow to reach the file.
533 specifies a file in the directory
535 which is a subdirectory of the
538 Within this directory the file named is `motd' which stands
539 for `message of the day'.
542 that begins with a slash is said to be an
544 pathname since it is specified from the absolute top of the entire
545 directory hierarchy of the system (the
548 which do not begin with `/' are interpreted as starting in the current
549 .I "working directory" ,
550 which is, by default, your
552 directory and can be changed dynamically by the
554 change directory command.
555 Such pathnames are said to be
557 to the working directory since they are found by starting
558 in the working directory and descending to lower levels of directories
561 of the pathname. If the pathname contains no slashes at all then the
562 file is contained in the working directory itself and the pathname is merely
563 the name of the file in this directory.
564 Absolute pathnames have no relation
565 to the working directory.
567 Most filenames consist of a number of alphanumeric characters and
569 In fact, all printing characters except `/' (slash) may appear in filenames.
570 It is inconvenient to have most non-alphabetic characters in filenames
571 because many of these have special meaning to the shell.
572 The character `.' (period) is not a shell-metacharacter and is often used
575 of a file name from the base of the name.
578 prog.c prog.o prog.errs prog.output
580 are four related files.
584 (a base portion being that part of the name that is left when a trailing
585 `.' and following characters which are not `.' are stripped off).
588 might be the source for a C program,
589 the file `prog.o' the corresponding object file,
591 `prog.errs' the errors resulting from a compilation of the program
593 `prog.output' the output of a run of the program.
595 If we wished to refer to all four of these files in a command, we could
600 This expression is expanded by the shell, before the command to which it is
601 an argument is executed, into a list of names which begin with `prog.'.
602 The character `*' here matches any sequence (including the empty sequence)
603 of characters in a file name.
604 The names which match are alphabetically sorted and placed in the
613 prog.c prog.errs prog.o prog.output
615 Note that the names are in sorted order here, and a different
616 order than we listed them above.
619 command receives four words as arguments, even though we only typed
620 one word as an argument directly.
621 The four words were generated by
622 .I "filename expansion"
623 of the one input word.
626 .I "filename expansion"
628 The character `?' matches any single character in a filename.
633 will echo a line of filenames; first those with one character names,
634 then those with two character names, and finally those with three
636 The names of each length will be independently sorted.
638 Another mechanism consists of a sequence of characters between `[' and `]'.
639 This metasequence matches any single character from the enclosed set.
648 in the example above.
649 We can also place two characters around a `\-' in this notation to denote
657 chap.1 chap.2 chap.3 chap.4 chap.5
660 This is shorthand for
664 and otherwise equivalent.
666 An important point to note is that if a list of argument words to
669 contains filename expansion syntax, and if this filename expansion syntax
670 fails to match any existing file names, then the shell considers this
671 to be an error and prints a diagnostic
675 and does not execute the command.
677 Another very important point is that files with the character `.' at the
678 beginning are treated specially.
679 Neither `*' or `?' or the `[' `]' mechanism will match it.
680 This prevents accidental matching of the filenames `.' and `..'
681 in the working directory which have special meaning to the system,
682 as well as other files such as
684 which are not normally
686 We will discuss the special role of the file
690 Another filename expansion mechanism gives access to the pathname of
693 directory of other users.
694 This notation consists of the character `~' (tilde) followed by another user's
696 For instance the word `~bill' would map to the pathname `/usr/bill'
697 if the home directory for `bill' was `/usr/bill'.
698 Since, on large systems, users may have login directories scattered over
699 many different disk volumes with different prefix directory names,
700 this notation provides a convenient way of accessing the files
703 A special case of this notation consists of a `~' alone, e.g. `~/mbox'.
704 This notation is expanded by the shell into the file `mbox' in your
706 directory, i.e. into `/usr/bill/mbox' for me on Ernie Co-vax, the UCB
707 Computer Science Department VAX machine, where this document was prepared.
708 This can be very useful if you have used
710 to change to another directory and have found a file you wish to
713 If I give the command
717 the shell will expand this command to
719 cp thatfile /usr/bill
721 since my home directory is /usr/bill.
723 There also exists a mechanism using the characters `{' and `}' for
724 abbreviating a set of words which have common parts but cannot
725 be abbreviated by the above mechanisms because they are not files,
726 are the names of files which do not yet exist,
727 are not thus conveniently described.
728 This mechanism will be described much later,
730 as it is used less frequently.
734 We have already seen a number of metacharacters used by the shell.
735 These metacharacters pose a problem in that we cannot use them directly
741 will not echo the character `*'.
742 It will either echo a sorted list of filenames in the
744 .I "working directory,"
745 or print the message `No match' if there are
746 no files in the working directory.
748 The recommended mechanism for placing characters which are neither numbers,
749 digits, `/', `.' or `\-' in an argument word to a command is to enclose
750 it with single quotation characters `\'', i.e.
754 There is one special character `!' which is used by the
756 mechanism of the shell and which cannot be
758 by placing it within `\'' characters.
759 It and the character `\'' itself can be preceded by a single `\e'
760 to prevent their special meaning.
769 These two mechanisms suffice to place any printing character into a word
770 which is an argument to a shell command. They can be combined, as in
778 since the first `\e' escaped the first `\'' and the `*' was enclosed
779 between `\'' characters.
783 When you are executing a command and the shell is
784 waiting for it to complete there are several ways
786 For instance if you type the command
790 the system will print a copy of a list of all users of the system
792 This is likely to continue for several minutes unless you stop it.
798 command by typing ^C on your terminal.*
800 *On some older Unix systems the \s-2DEL\s0 or \s-2RUBOUT\s0 key
801 has the same effect. "stty all" will tell you the INTR key value.
805 does not take any precautions to avoid or otherwise handle this signal
808 will cause it to terminate.
809 The shell notices that
811 has terminated and prompts you again with `% '.
812 If you hit \s-2INTERRUPT\s0 again, the shell will just
813 repeat its prompt since it handles \s-2INTERRUPT\s0 signals
814 and chooses to continue to execute commands rather than terminating
817 did, which would have the effect of logging you out.
819 Another way in which many programs terminate is when they get an end-of-file
820 from their standard input.
823 program in the first example above was terminated when we typed a ^D
824 which generates an end-of-file from the standard input.
825 The shell also terminates when it gets an end-of-file printing `logout';
826 \s-2UNIX\s0 then logs you off the system.
827 Since this means that typing too many ^D's can accidentally log us off,
828 the shell has a mechanism for preventing this.
831 option will be discussed in section 2.2.
833 If a command has its standard input redirected from a file, then it will
834 normally terminate when it reaches the end of this file.
837 mail bill < prepared.text
839 the mail command will terminate without our typing a ^D.
840 This is because it read to the end-of-file of our file
841 `prepared.text' in which we placed a message for `bill' with an editor program.
842 We could also have done
844 cat prepared.text \||\| mail bill
848 command would then have written the text through the pipe to the
849 standard input of the mail command.
852 command completed it would have terminated,
853 closing down the pipeline
856 command would have received an end-of-file from it and terminated.
857 Using a pipe here is more complicated than redirecting input
858 so we would more likely use the first form.
859 These commands could also have been stopped by sending an \s-2INTERRUPT\s0.
861 Another possibility for stopping a command is to suspend its execution
862 temporarily, with the possibility of continuing execution later. This is
863 done by sending a \s-2STOP\s0 signal via typing a ^Z.
864 This signal causes all commands running on the terminal
865 (usually one but more if a pipeline is executing) to become suspended.
866 The shell notices that the command(s) have been suspended, types
867 `Stopped' and then prompts for a new command.
868 The previously executing command has been suspended, but otherwise
869 unaffected by the \s-2STOP\s0 signal. Any other commands can be executed
870 while the original command remains suspended. The suspended command can
871 be continued using the
873 command with no arguments. The shell will then retype the command
874 to remind you which command is being continued, and cause the command
875 to resume execution. Unless any input files in use by the suspended
876 command have been changed in the meantime, the suspension has no effect
877 whatsoever on the execution of the command. This feature can be very useful
878 during editing, when you need to look at another file before continuing.
880 example of command suspension follows.
883 Someone just copied a big file into my directory and its name is
892 [1] + Stopped mail harold
895 funnyfile. Do you know who did it?
900 In this example someone was sending a message to Harold and forgot the
901 name of the file he wanted to mention. The mail command was suspended
902 by typing ^Z. When the shell noticed that the mail program was
903 suspended, it typed `Stopped' and prompted for a new command. Then the
905 command was typed to find out the name of the file. The
907 command was run to find out which command was suspended.
910 command was typed to continue execution of the mail program. Input
911 to the mail program was then continued and ended with a ^D
912 which indicated the end of the message at which time the mail
913 program typed EOT. The
915 command will show which commands are suspended.
916 The ^Z should only be typed at the beginning of a line since
917 everything typed on the current line is discarded when a signal is sent
918 from the keyboard. This also happens on \s-2INTERRUPT\s0, and \s-2QUIT\s0
919 signals. More information on
920 suspending jobs and controlling them is given in
923 If you write or run programs which are not fully debugged then it may
924 be necessary to stop them somewhat ungracefully.
925 This can be done by sending them a \s-2QUIT\s0
926 signal, sent by typing a ^\e.
927 This will usually provoke the shell to produce a message like:
931 indicating that a file
932 `core' has been created containing information about the running program's
933 state when it terminated due to the \s-2QUIT\s0 signal.
934 You can examine this file yourself, or forward information to the
935 maintainer of the program telling him/her where the
939 If you run background commands (as explained in section 2.6) then these
940 commands will ignore \s-2INTERRUPT\s0 and \s-2QUIT\s0 signals at the
941 terminal. To stop them you must use the
943 command. See section 2.6 for an example.
945 If you want to examine the output of a command without having it move
946 off the screen as the output of the
950 command will, you can use the command
956 program pauses after each complete screenful and types `\-\-More\-\-'
957 at which point you can hit a space to get another screenful, a return
958 to get another line, a `?' to get some help on other commands, or a `q' to end the
960 program. You can also use more as a filter, i.e.
962 cat /etc/passwd | more
964 works just like the more simple more command above.
966 For stopping output of commands not involving
969 ^S key to stop the typeout. The typeout will resume when you
970 hit ^Q or any other key, but ^Q is normally used because
971 it only restarts the output and does not become input to the program
972 which is running. This works well on low-speed terminals, but at 9600
973 baud it is hard to type ^S and ^Q fast enough to paginate
974 the output nicely, and a program like
978 An additional possibility is to use the ^O flush output
979 character; when this character is typed, all output from the current
980 command is thrown away (quickly) until the next input read occurs
981 or until the next shell prompt. This can be used to allow a command
982 to complete without having to suffer through the output on a slow
983 terminal; ^O is a toggle, so flushing can be turned off by
984 typing ^O again while output is being flushed.
988 We have so far seen a number of mechanisms of the shell and learned a lot
989 about the way in which it operates.
990 The remaining sections will go yet further into the internals of the
991 shell, but you will surely want to try using the
992 shell before you go any further.
993 To try it you can log in to \s-2UNIX\s0 and type the following
994 command to the system:
998 Here `myname' should be replaced by the name you typed to
999 the system prompt of `login:' to get onto the system.
1000 Thus I would use `chsh bill /bin/csh'.
1002 You only have to do this once; it takes effect at next login.
1004 You are now ready to try using
1007 Before you do the `chsh' command, the shell you are using when
1008 you log into the system is `/bin/sh'.
1009 In fact, much of the above discussion is applicable to `/bin/sh'.
1010 The next section will introduce many features particular to
1012 so you should change your shell to
1014 before you begin reading it.