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 $
34 .\" $DragonFly: src/bin/csh/USD.doc/csh.1,v 1.2 2003/06/17 04:22:49 dillon Exp $
36 .EH 'USD:4-%''An Introduction to the C shell'
37 .OH 'An Introduction to the C shell''USD:4-%'
40 An Introduction to the C shell
43 (revised for 4.3BSD by Mark Seiden)
45 Computer Science Division
47 Department of Electrical Engineering and Computer Science
49 University of California, Berkeley
51 Berkeley, California 94720
54 is a new command language interpreter for
57 It incorporates good features of other shells and a
59 mechanism similar to the
62 While incorporating many features of other shells which make
63 writing shell programs (shell scripts) easier,
64 most of the features unique to
66 are designed more for the interactive \s-2UNIX\s0 user.
69 users who have read a general introduction to the system
70 will find a valuable basic explanation of the shell here.
71 Simple terminal interaction with
73 is possible after reading just the first section of this document.
74 The second section describes the shell's capabilities which you can
75 explore after you have begun to become acquainted with the shell.
76 Later sections introduce features which are useful, but not necessary
77 for all users of the shell.
79 Additional information includes an appendix listing special characters of the shell
80 and a glossary of terms and commands introduced in this manual.
88 is a command language interpreter.
90 is the name of one particular command interpreter on
92 The primary purpose of
94 is to translate command lines typed at a terminal into
95 system actions, such as invocation of other programs.
97 is a user program just like any you might write.
100 will be a very useful program for you
101 in interacting with the \s-2UNIX\s0 system.
103 In addition to this document, you will want to refer to a copy
104 of the \s-2UNIX\s0 User Reference Manual.
107 documentation in section 1 of the manual provides a full description of all
108 features of the shell and is the definitive reference for questions
111 Many words in this document are shown in
113 These are important words;
114 names of commands, and words which have special meaning in discussing
115 the shell and \s-2UNIX\s0.
116 Many of the words are defined in a glossary at the end of this document.
117 If you don't know what is meant by a word, you should look
118 for it in the glossary.
122 Numerous people have provided good input about previous versions
125 and aided in its debugging and in the debugging of its documentation.
126 I would especially like to thank Michael Ubell
127 who made the crucial observation that history commands could be
128 done well over the word structure of input text, and implemented
129 a prototype history mechanism in an older version of the shell.
130 Eric Allman has also provided a large number of useful comments on the
131 shell, helping to unify those concepts which are present and to identify
132 and eliminate useless and marginally useful features.
133 Mike O'Brien suggested the pathname hashing
134 mechanism which speeds command execution.
135 Jim Kulp added the job control and directory stack primitives and
136 added their documentation to this introduction.
140 Terminal usage of the shell
142 The basic notion of commands
148 acts mostly as a medium through which other
151 While it has a set of
153 functions which it performs directly,
154 most commands cause execution of programs that are, in fact,
155 external to the shell.
156 The shell is thus distinguished from the command interpreters of other
157 systems both by the fact that it is just a user program, and by the fact
158 that it is used almost exclusively as a mechanism for invoking other programs.
161 in the \s-2UNIX\s0 system consist of a list of strings or
171 consists of two words.
174 names the command to be executed, in this case the
175 mail program which sends messages to other users.
176 The shell uses the name of the command in attempting to execute it for you.
177 It will look in a number of
179 for a file with the name
181 which is expected to contain the mail program.
183 The rest of the words of the command are given as
185 to the command itself when it is executed.
186 In this case we specified also the argument
188 which is interpreted by the
190 program to be the name of a user to whom mail is to be sent.
191 In normal terminal usage we might use the
196 I have a question about the csh documentation.
197 My document seems to be missing page 5.
198 Does a page five exist?
204 Here we typed a message to send to
206 and ended this message with a ^D which sent an end-of-file to
208 (Here and throughout this document, the notation ``^\fIx\fR''
209 is to be read ``control-\fIx\fR'' and represents the striking of the \fIx\fR
210 key while the control key is held down.)
212 then echoed the characters `EOT' and transmitted our message.
213 The characters `% ' were printed before and after the mail command
214 by the shell to indicate that input was needed.
216 After typing the `% ' prompt the shell was reading command input from
218 We typed a complete command `mail bill'.
219 The shell then executed the
221 program with argument
223 and went dormant waiting for it to complete.
224 The mail program then read input from our terminal until we signalled
225 an end-of-file via typing a ^D after which the shell noticed
226 that mail had completed
227 and signaled us that it was ready to read from the terminal again by
228 printing another `% ' prompt.
230 This is the essential pattern of all interaction with \s-2UNIX\s0
232 A complete command is typed at the terminal, the shell executes
233 the command and when this execution completes, it prompts for a new command.
234 If you run the editor for an hour, the shell will patiently wait for
235 you to finish editing and obediently prompt you again whenever you finish
238 An example of a useful command you can execute now is the
240 command, which sets the default
244 characters on your terminal \- the erase character erases the last
245 character you typed and the kill character erases the entire line you
247 By default, the erase character is the delete key (equivalent to `^?')
248 and the kill character is `^U'. Some people prefer to make the erase character
249 the backspace key (equivalent to `^H').
250 You can make this be true by typing
254 which tells the program
256 to set the erase character to tset's default setting for this character
261 A useful notion in \s-2UNIX\s0 is that of a
264 While many arguments to commands specify file names or user names,
265 some arguments rather specify an optional capability of the command
266 which you wish to invoke.
267 By convention, such arguments begin with the character `\-' (hyphen).
272 will produce a list of the files in the current
273 .I "working directory" .
276 is the size option, and
282 to also give, for each file the size of the file in blocks of 512
284 The manual section for each command in the \s-2UNIX\s0 reference manual
285 gives the available options for each command.
288 command has a large number of useful and interesting options.
289 Most other commands have either no options or only one or two options.
290 It is hard to remember options of commands which are not used very
291 frequently, so most \s-2UNIX\s0 utilities perform only one or two functions
292 rather than having a large number of hard to remember options.
296 Commands that normally read input or write output on the terminal
297 can also be executed with this input and/or output done to
300 Thus suppose we wish to save the current date in a file called `now'.
305 will print the current date on our terminal.
306 This is because our terminal is the default
308 for the date command and the date command prints the date on its
314 of a command through a
317 `>' and the name of the file where output is to be placed.
324 command such that its standard output is
325 the file `now' rather than the terminal.
326 Thus this command places the current date and time into the file `now'.
327 It is important to know that the
329 command was unaware that its output was going to a file rather than
331 The shell performed this
333 before the command began executing.
335 One other thing to note here is that the file `now'
336 need not have existed before the
338 command was executed; the shell would have created the file if it did
340 And if the file did exist?
341 If it had existed previously these previous contents would have been discarded!
344 exists to prevent this from happening accidentally;
345 it is discussed in section 2.2.
347 The system normally keeps files which you create with `>' and all other files.
348 Thus the default is for files to be permanent. If you wish to create a file
349 which will be removed automatically, you can begin its name with a `#'
350 character, this `scratch' character denotes the fact that the file will
353 *Note that if your erase character is a `#', you will have to precede the
354 `#' with a `\e'. The fact that the `#' character is the old (pre-\s-2CRT\s0)
355 standard erase character means that it seldom appears in a file name, and
356 allows this convention to be used for scratch files. If you are using a
357 \s-2CRT\s0, your erase character should be a ^H, as we demonstrated
358 in section 1.1 how this could be set up.
360 The system will remove such files after a couple of days,
361 or sooner if file space becomes very tight.
364 command above, we don't really want to save the output forever, so we
370 Metacharacters in the shell
372 The shell has a large number of
373 special characters (like `>')
374 which indicate special functions.
375 We say that these notations have
379 meaning to the shell.
380 In general, most characters which are neither letters nor digits
381 have special meaning to the shell.
382 We shall shortly learn a means of
384 which allows us to use
386 without the shell treating them in any special way.
388 Metacharacters normally have effect only when the shell is reading
390 We need not worry about placing shell metacharacters in a letter
393 or when we are typing in text or data to some other program.
394 Note that the shell is only reading input when it has prompted with
395 `% ' (although we can type our input even before it prompts).
397 Input from files; pipelines
399 We learned above how to
405 It is also possible to redirect the
407 of a command from a file.
408 This is not often necessary since most commands will read from
409 a file whose name is given as an argument.
410 We can give the command
416 command with standard input, where the command normally
417 reads its input, from the file
419 We would more likely say
425 command open the file
427 for input itself since this is less to type.
429 We should note that if we just typed
433 then the sort program would sort lines from its
437 the standard input, it would sort lines as we typed them on the terminal
438 until we typed a ^D to indicate an end-of-file.
440 A most useful capability is the ability to combine the standard output
441 of one command with the standard input of another, i.e. to run the
442 commands in a sequence known as a
444 For instance the command
448 normally produces a list of the files in our directory with the size
449 of each in blocks of 512 characters.
450 If we are interested in learning which of our files is largest we
451 may wish to have this sorted by size rather than by name, which is
452 the default way in which
455 We could look at the many options of
457 to see if there was an option to do this but would eventually discover
459 Instead we can use a couple of simple options of the
461 command, combining it with
467 option of sort specifies a numeric sort rather than an alphabetic sort.
472 specifies that the output of the
474 command run with the option
480 run with the numeric sort option.
481 This would give us a sorted list of our files by size, but with the
483 We could then use the
485 reverse sort option and the
487 command in combination with the previous command doing
489 ls \-s | sort \-n \-r | head \-5
491 Here we have taken a list of our files sorted alphabetically,
492 each with the size in blocks.
493 We have run this to the standard input of the
495 command asking it to sort numerically in reverse order (largest first).
496 This output has then been run into the command
498 which gives us the first few lines.
499 In this case we have asked
501 for the first 5 lines.
502 Thus this command gives us the names and sizes of our 5 largest files.
504 The notation introduced above is called the
507 Commands separated by `\||\|' characters are connected together by the
508 shell and the standard output of each is run into the standard input of the
510 The leftmost command in a pipeline will normally take its standard
511 input from the terminal and the rightmost will place its standard
512 output on the terminal.
513 Other examples of pipelines will be given later when we discuss the
515 one important use of pipes which is illustrated there is in the
516 routing of information to the line printer.
520 Many commands to be executed will need the names of files as arguments.
523 consist of a number of
526 Each component except the last names a directory in which the next
527 component resides, in effect specifying the
529 of directories to follow to reach the file.
534 specifies a file in the directory
536 which is a subdirectory of the
539 Within this directory the file named is `motd' which stands
540 for `message of the day'.
543 that begins with a slash is said to be an
545 pathname since it is specified from the absolute top of the entire
546 directory hierarchy of the system (the
549 which do not begin with `/' are interpreted as starting in the current
550 .I "working directory" ,
551 which is, by default, your
553 directory and can be changed dynamically by the
555 change directory command.
556 Such pathnames are said to be
558 to the working directory since they are found by starting
559 in the working directory and descending to lower levels of directories
562 of the pathname. If the pathname contains no slashes at all then the
563 file is contained in the working directory itself and the pathname is merely
564 the name of the file in this directory.
565 Absolute pathnames have no relation
566 to the working directory.
568 Most filenames consist of a number of alphanumeric characters and
570 In fact, all printing characters except `/' (slash) may appear in filenames.
571 It is inconvenient to have most non-alphabetic characters in filenames
572 because many of these have special meaning to the shell.
573 The character `.' (period) is not a shell-metacharacter and is often used
576 of a file name from the base of the name.
579 prog.c prog.o prog.errs prog.output
581 are four related files.
585 (a base portion being that part of the name that is left when a trailing
586 `.' and following characters which are not `.' are stripped off).
589 might be the source for a C program,
590 the file `prog.o' the corresponding object file,
592 `prog.errs' the errors resulting from a compilation of the program
594 `prog.output' the output of a run of the program.
596 If we wished to refer to all four of these files in a command, we could
601 This expression is expanded by the shell, before the command to which it is
602 an argument is executed, into a list of names which begin with `prog.'.
603 The character `*' here matches any sequence (including the empty sequence)
604 of characters in a file name.
605 The names which match are alphabetically sorted and placed in the
614 prog.c prog.errs prog.o prog.output
616 Note that the names are in sorted order here, and a different
617 order than we listed them above.
620 command receives four words as arguments, even though we only typed
621 one word as an argument directly.
622 The four words were generated by
623 .I "filename expansion"
624 of the one input word.
627 .I "filename expansion"
629 The character `?' matches any single character in a filename.
634 will echo a line of filenames; first those with one character names,
635 then those with two character names, and finally those with three
637 The names of each length will be independently sorted.
639 Another mechanism consists of a sequence of characters between `[' and `]'.
640 This metasequence matches any single character from the enclosed set.
649 in the example above.
650 We can also place two characters around a `\-' in this notation to denote
658 chap.1 chap.2 chap.3 chap.4 chap.5
661 This is shorthand for
665 and otherwise equivalent.
667 An important point to note is that if a list of argument words to
670 contains filename expansion syntax, and if this filename expansion syntax
671 fails to match any existing file names, then the shell considers this
672 to be an error and prints a diagnostic
676 and does not execute the command.
678 Another very important point is that files with the character `.' at the
679 beginning are treated specially.
680 Neither `*' or `?' or the `[' `]' mechanism will match it.
681 This prevents accidental matching of the filenames `.' and `..'
682 in the working directory which have special meaning to the system,
683 as well as other files such as
685 which are not normally
687 We will discuss the special role of the file
691 Another filename expansion mechanism gives access to the pathname of
694 directory of other users.
695 This notation consists of the character `~' (tilde) followed by another user's
697 For instance the word `~bill' would map to the pathname `/usr/bill'
698 if the home directory for `bill' was `/usr/bill'.
699 Since, on large systems, users may have login directories scattered over
700 many different disk volumes with different prefix directory names,
701 this notation provides a convenient way of accessing the files
704 A special case of this notation consists of a `~' alone, e.g. `~/mbox'.
705 This notation is expanded by the shell into the file `mbox' in your
707 directory, i.e. into `/usr/bill/mbox' for me on Ernie Co-vax, the UCB
708 Computer Science Department VAX machine, where this document was prepared.
709 This can be very useful if you have used
711 to change to another directory and have found a file you wish to
714 If I give the command
718 the shell will expand this command to
720 cp thatfile /usr/bill
722 since my home directory is /usr/bill.
724 There also exists a mechanism using the characters `{' and `}' for
725 abbreviating a set of words which have common parts but cannot
726 be abbreviated by the above mechanisms because they are not files,
727 are the names of files which do not yet exist,
728 are not thus conveniently described.
729 This mechanism will be described much later,
731 as it is used less frequently.
735 We have already seen a number of metacharacters used by the shell.
736 These metacharacters pose a problem in that we cannot use them directly
742 will not echo the character `*'.
743 It will either echo a sorted list of filenames in the
745 .I "working directory,"
746 or print the message `No match' if there are
747 no files in the working directory.
749 The recommended mechanism for placing characters which are neither numbers,
750 digits, `/', `.' or `\-' in an argument word to a command is to enclose
751 it with single quotation characters `\'', i.e.
755 There is one special character `!' which is used by the
757 mechanism of the shell and which cannot be
759 by placing it within `\'' characters.
760 It and the character `\'' itself can be preceded by a single `\e'
761 to prevent their special meaning.
770 These two mechanisms suffice to place any printing character into a word
771 which is an argument to a shell command. They can be combined, as in
779 since the first `\e' escaped the first `\'' and the `*' was enclosed
780 between `\'' characters.
784 When you are executing a command and the shell is
785 waiting for it to complete there are several ways
787 For instance if you type the command
791 the system will print a copy of a list of all users of the system
793 This is likely to continue for several minutes unless you stop it.
799 command by typing ^C on your terminal.*
801 *On some older Unix systems the \s-2DEL\s0 or \s-2RUBOUT\s0 key
802 has the same effect. "stty all" will tell you the INTR key value.
806 does not take any precautions to avoid or otherwise handle this signal
809 will cause it to terminate.
810 The shell notices that
812 has terminated and prompts you again with `% '.
813 If you hit \s-2INTERRUPT\s0 again, the shell will just
814 repeat its prompt since it handles \s-2INTERRUPT\s0 signals
815 and chooses to continue to execute commands rather than terminating
818 did, which would have the effect of logging you out.
820 Another way in which many programs terminate is when they get an end-of-file
821 from their standard input.
824 program in the first example above was terminated when we typed a ^D
825 which generates an end-of-file from the standard input.
826 The shell also terminates when it gets an end-of-file printing `logout';
827 \s-2UNIX\s0 then logs you off the system.
828 Since this means that typing too many ^D's can accidentally log us off,
829 the shell has a mechanism for preventing this.
832 option will be discussed in section 2.2.
834 If a command has its standard input redirected from a file, then it will
835 normally terminate when it reaches the end of this file.
838 mail bill < prepared.text
840 the mail command will terminate without our typing a ^D.
841 This is because it read to the end-of-file of our file
842 `prepared.text' in which we placed a message for `bill' with an editor program.
843 We could also have done
845 cat prepared.text \||\| mail bill
849 command would then have written the text through the pipe to the
850 standard input of the mail command.
853 command completed it would have terminated,
854 closing down the pipeline
857 command would have received an end-of-file from it and terminated.
858 Using a pipe here is more complicated than redirecting input
859 so we would more likely use the first form.
860 These commands could also have been stopped by sending an \s-2INTERRUPT\s0.
862 Another possibility for stopping a command is to suspend its execution
863 temporarily, with the possibility of continuing execution later. This is
864 done by sending a \s-2STOP\s0 signal via typing a ^Z.
865 This signal causes all commands running on the terminal
866 (usually one but more if a pipeline is executing) to become suspended.
867 The shell notices that the command(s) have been suspended, types
868 `Stopped' and then prompts for a new command.
869 The previously executing command has been suspended, but otherwise
870 unaffected by the \s-2STOP\s0 signal. Any other commands can be executed
871 while the original command remains suspended. The suspended command can
872 be continued using the
874 command with no arguments. The shell will then retype the command
875 to remind you which command is being continued, and cause the command
876 to resume execution. Unless any input files in use by the suspended
877 command have been changed in the meantime, the suspension has no effect
878 whatsoever on the execution of the command. This feature can be very useful
879 during editing, when you need to look at another file before continuing.
881 example of command suspension follows.
884 Someone just copied a big file into my directory and its name is
893 [1] + Stopped mail harold
896 funnyfile. Do you know who did it?
901 In this example someone was sending a message to Harold and forgot the
902 name of the file he wanted to mention. The mail command was suspended
903 by typing ^Z. When the shell noticed that the mail program was
904 suspended, it typed `Stopped' and prompted for a new command. Then the
906 command was typed to find out the name of the file. The
908 command was run to find out which command was suspended.
911 command was typed to continue execution of the mail program. Input
912 to the mail program was then continued and ended with a ^D
913 which indicated the end of the message at which time the mail
914 program typed EOT. The
916 command will show which commands are suspended.
917 The ^Z should only be typed at the beginning of a line since
918 everything typed on the current line is discarded when a signal is sent
919 from the keyboard. This also happens on \s-2INTERRUPT\s0, and \s-2QUIT\s0
920 signals. More information on
921 suspending jobs and controlling them is given in
924 If you write or run programs which are not fully debugged then it may
925 be necessary to stop them somewhat ungracefully.
926 This can be done by sending them a \s-2QUIT\s0
927 signal, sent by typing a ^\e.
928 This will usually provoke the shell to produce a message like:
932 indicating that a file
933 `core' has been created containing information about the running program's
934 state when it terminated due to the \s-2QUIT\s0 signal.
935 You can examine this file yourself, or forward information to the
936 maintainer of the program telling him/her where the
940 If you run background commands (as explained in section 2.6) then these
941 commands will ignore \s-2INTERRUPT\s0 and \s-2QUIT\s0 signals at the
942 terminal. To stop them you must use the
944 command. See section 2.6 for an example.
946 If you want to examine the output of a command without having it move
947 off the screen as the output of the
951 command will, you can use the command
957 program pauses after each complete screenful and types `\-\-More\-\-'
958 at which point you can hit a space to get another screenful, a return
959 to get another line, a `?' to get some help on other commands, or a `q' to end the
961 program. You can also use more as a filter, i.e.
963 cat /etc/passwd | more
965 works just like the more simple more command above.
967 For stopping output of commands not involving
970 ^S key to stop the typeout. The typeout will resume when you
971 hit ^Q or any other key, but ^Q is normally used because
972 it only restarts the output and does not become input to the program
973 which is running. This works well on low-speed terminals, but at 9600
974 baud it is hard to type ^S and ^Q fast enough to paginate
975 the output nicely, and a program like
979 An additional possibility is to use the ^O flush output
980 character; when this character is typed, all output from the current
981 command is thrown away (quickly) until the next input read occurs
982 or until the next shell prompt. This can be used to allow a command
983 to complete without having to suffer through the output on a slow
984 terminal; ^O is a toggle, so flushing can be turned off by
985 typing ^O again while output is being flushed.
989 We have so far seen a number of mechanisms of the shell and learned a lot
990 about the way in which it operates.
991 The remaining sections will go yet further into the internals of the
992 shell, but you will surely want to try using the
993 shell before you go any further.
994 To try it you can log in to \s-2UNIX\s0 and type the following
995 command to the system:
999 Here `myname' should be replaced by the name you typed to
1000 the system prompt of `login:' to get onto the system.
1001 Thus I would use `chsh bill /bin/csh'.
1003 You only have to do this once; it takes effect at next login.
1005 You are now ready to try using
1008 Before you do the `chsh' command, the shell you are using when
1009 you log into the system is `/bin/sh'.
1010 In fact, much of the above discussion is applicable to `/bin/sh'.
1011 The next section will introduce many features particular to
1013 so you should change your shell to
1015 before you begin reading it.