1 .\" $NetBSD: csh.1,v 1.5 2003/08/07 09:05:08 agc Exp $
3 .\" Copyright (c) 1980, 1993
4 .\" The Regents of the University of California. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" @(#)csh.1 8.1 (Berkeley) 6/8/93
32 .EH 'USD:4-%''An Introduction to the C shell'
33 .OH 'An Introduction to the C shell''USD:4-%'
36 An Introduction to the C shell
39 (revised for 4.3BSD by Mark Seiden)
41 Computer Science Division
43 Department of Electrical Engineering and Computer Science
45 University of California, Berkeley
47 Berkeley, California 94720
50 is a new command language interpreter for
53 It incorporates good features of other shells and a
55 mechanism similar to the
58 While incorporating many features of other shells which make
59 writing shell programs (shell scripts) easier,
60 most of the features unique to
62 are designed more for the interactive \s-2UNIX\s0 user.
65 users who have read a general introduction to the system
66 will find a valuable basic explanation of the shell here.
67 Simple terminal interaction with
69 is possible after reading just the first section of this document.
70 The second section describes the shell's capabilities which you can
71 explore after you have begun to become acquainted with the shell.
72 Later sections introduce features which are useful, but not necessary
73 for all users of the shell.
75 Additional information includes an appendix listing special characters of the shell
76 and a glossary of terms and commands introduced in this manual.
84 is a command language interpreter.
86 is the name of one particular command interpreter on
88 The primary purpose of
90 is to translate command lines typed at a terminal into
91 system actions, such as invocation of other programs.
93 is a user program just like any you might write.
96 will be a very useful program for you
97 in interacting with the \s-2UNIX\s0 system.
99 In addition to this document, you will want to refer to a copy
100 of the \s-2UNIX\s0 User Reference Manual.
103 documentation in section 1 of the manual provides a full description of all
104 features of the shell and is the definitive reference for questions
107 Many words in this document are shown in
109 These are important words;
110 names of commands, and words which have special meaning in discussing
111 the shell and \s-2UNIX\s0.
112 Many of the words are defined in a glossary at the end of this document.
113 If you don't know what is meant by a word, you should look
114 for it in the glossary.
118 Numerous people have provided good input about previous versions
121 and aided in its debugging and in the debugging of its documentation.
122 I would especially like to thank Michael Ubell
123 who made the crucial observation that history commands could be
124 done well over the word structure of input text, and implemented
125 a prototype history mechanism in an older version of the shell.
126 Eric Allman has also provided a large number of useful comments on the
127 shell, helping to unify those concepts which are present and to identify
128 and eliminate useless and marginally useful features.
129 Mike O'Brien suggested the pathname hashing
130 mechanism which speeds command execution.
131 Jim Kulp added the job control and directory stack primitives and
132 added their documentation to this introduction.
136 Terminal usage of the shell
138 The basic notion of commands
144 acts mostly as a medium through which other
147 While it has a set of
149 functions which it performs directly,
150 most commands cause execution of programs that are, in fact,
151 external to the shell.
152 The shell is thus distinguished from the command interpreters of other
153 systems both by the fact that it is just a user program, and by the fact
154 that it is used almost exclusively as a mechanism for invoking other programs.
157 in the \s-2UNIX\s0 system consist of a list of strings or
167 consists of two words.
170 names the command to be executed, in this case the
171 mail program which sends messages to other users.
172 The shell uses the name of the command in attempting to execute it for you.
173 It will look in a number of
175 for a file with the name
177 which is expected to contain the mail program.
179 The rest of the words of the command are given as
181 to the command itself when it is executed.
182 In this case we specified also the argument
184 which is interpreted by the
186 program to be the name of a user to whom mail is to be sent.
187 In normal terminal usage we might use the
192 I have a question about the csh documentation.
193 My document seems to be missing page 5.
194 Does a page five exist?
200 Here we typed a message to send to
202 and ended this message with a ^D which sent an end-of-file to
204 (Here and throughout this document, the notation ``^\fIx\fR''
205 is to be read ``control-\fIx\fR'' and represents the striking of the \fIx\fR
206 key while the control key is held down.)
208 then echoed the characters `EOT' and transmitted our message.
209 The characters `% ' were printed before and after the mail command
210 by the shell to indicate that input was needed.
212 After typing the `% ' prompt the shell was reading command input from
214 We typed a complete command `mail bill'.
215 The shell then executed the
217 program with argument
219 and went dormant waiting for it to complete.
220 The mail program then read input from our terminal until we signalled
221 an end-of-file via typing a ^D after which the shell noticed
222 that mail had completed
223 and signaled us that it was ready to read from the terminal again by
224 printing another `% ' prompt.
226 This is the essential pattern of all interaction with \s-2UNIX\s0
228 A complete command is typed at the terminal, the shell executes
229 the command and when this execution completes, it prompts for a new command.
230 If you run the editor for an hour, the shell will patiently wait for
231 you to finish editing and obediently prompt you again whenever you finish
234 An example of a useful command you can execute now is the
236 command, which sets the default
240 characters on your terminal \- the erase character erases the last
241 character you typed and the kill character erases the entire line you
243 By default, the erase character is the delete key (equivalent to `^?')
244 and the kill character is `^U'. Some people prefer to make the erase character
245 the backspace key (equivalent to `^H').
246 You can make this be true by typing
250 which tells the program
252 to set the erase character to tset's default setting for this character
257 A useful notion in \s-2UNIX\s0 is that of a
260 While many arguments to commands specify file names or user names,
261 some arguments rather specify an optional capability of the command
262 which you wish to invoke.
263 By convention, such arguments begin with the character `\-' (hyphen).
268 will produce a list of the files in the current
269 .I "working directory" .
272 is the size option, and
278 to also give, for each file the size of the file in blocks of 512
280 The manual section for each command in the \s-2UNIX\s0 reference manual
281 gives the available options for each command.
284 command has a large number of useful and interesting options.
285 Most other commands have either no options or only one or two options.
286 It is hard to remember options of commands which are not used very
287 frequently, so most \s-2UNIX\s0 utilities perform only one or two functions
288 rather than having a large number of hard to remember options.
292 Commands that normally read input or write output on the terminal
293 can also be executed with this input and/or output done to
296 Thus suppose we wish to save the current date in a file called `now'.
301 will print the current date on our terminal.
302 This is because our terminal is the default
304 for the date command and the date command prints the date on its
310 of a command through a
313 `>' and the name of the file where output is to be placed.
320 command such that its standard output is
321 the file `now' rather than the terminal.
322 Thus this command places the current date and time into the file `now'.
323 It is important to know that the
325 command was unaware that its output was going to a file rather than
327 The shell performed this
329 before the command began executing.
331 One other thing to note here is that the file `now'
332 need not have existed before the
334 command was executed; the shell would have created the file if it did
336 And if the file did exist?
337 If it had existed previously these previous contents would have been discarded!
340 exists to prevent this from happening accidentally;
341 it is discussed in section 2.2.
343 The system normally keeps files which you create with `>' and all other files.
344 Thus the default is for files to be permanent. If you wish to create a file
345 which will be removed automatically, you can begin its name with a `#'
346 character, this `scratch' character denotes the fact that the file will
349 *Note that if your erase character is a `#', you will have to precede the
350 `#' with a `\e'. The fact that the `#' character is the old (pre-\s-2CRT\s0)
351 standard erase character means that it seldom appears in a file name, and
352 allows this convention to be used for scratch files. If you are using a
353 \s-2CRT\s0, your erase character should be a ^H, as we demonstrated
354 in section 1.1 how this could be set up.
356 The system will remove such files after a couple of days,
357 or sooner if file space becomes very tight.
360 command above, we don't really want to save the output forever, so we
366 Metacharacters in the shell
368 The shell has a large number of
369 special characters (like `>')
370 which indicate special functions.
371 We say that these notations have
375 meaning to the shell.
376 In general, most characters which are neither letters nor digits
377 have special meaning to the shell.
378 We shall shortly learn a means of
380 which allows us to use
382 without the shell treating them in any special way.
384 Metacharacters normally have effect only when the shell is reading
386 We need not worry about placing shell metacharacters in a letter
389 or when we are typing in text or data to some other program.
390 Note that the shell is only reading input when it has prompted with
391 `% ' (although we can type our input even before it prompts).
393 Input from files; pipelines
395 We learned above how to
401 It is also possible to redirect the
403 of a command from a file.
404 This is not often necessary since most commands will read from
405 a file whose name is given as an argument.
406 We can give the command
412 command with standard input, where the command normally
413 reads its input, from the file
415 We would more likely say
421 command open the file
423 for input itself since this is less to type.
425 We should note that if we just typed
429 then the sort program would sort lines from its
433 the standard input, it would sort lines as we typed them on the terminal
434 until we typed a ^D to indicate an end-of-file.
436 A most useful capability is the ability to combine the standard output
437 of one command with the standard input of another, i.e. to run the
438 commands in a sequence known as a
440 For instance the command
444 normally produces a list of the files in our directory with the size
445 of each in blocks of 512 characters.
446 If we are interested in learning which of our files is largest we
447 may wish to have this sorted by size rather than by name, which is
448 the default way in which
451 We could look at the many options of
453 to see if there was an option to do this but would eventually discover
455 Instead we can use a couple of simple options of the
457 command, combining it with
463 option of sort specifies a numeric sort rather than an alphabetic sort.
468 specifies that the output of the
470 command run with the option
476 run with the numeric sort option.
477 This would give us a sorted list of our files by size, but with the
479 We could then use the
481 reverse sort option and the
483 command in combination with the previous command doing
485 ls \-s | sort \-n \-r | head \-5
487 Here we have taken a list of our files sorted alphabetically,
488 each with the size in blocks.
489 We have run this to the standard input of the
491 command asking it to sort numerically in reverse order (largest first).
492 This output has then been run into the command
494 which gives us the first few lines.
495 In this case we have asked
497 for the first 5 lines.
498 Thus this command gives us the names and sizes of our 5 largest files.
500 The notation introduced above is called the
503 Commands separated by `\||\|' characters are connected together by the
504 shell and the standard output of each is run into the standard input of the
506 The leftmost command in a pipeline will normally take its standard
507 input from the terminal and the rightmost will place its standard
508 output on the terminal.
509 Other examples of pipelines will be given later when we discuss the
511 one important use of pipes which is illustrated there is in the
512 routing of information to the line printer.
516 Many commands to be executed will need the names of files as arguments.
519 consist of a number of
522 Each component except the last names a directory in which the next
523 component resides, in effect specifying the
525 of directories to follow to reach the file.
530 specifies a file in the directory
532 which is a subdirectory of the
535 Within this directory the file named is `motd' which stands
536 for `message of the day'.
539 that begins with a slash is said to be an
541 pathname since it is specified from the absolute top of the entire
542 directory hierarchy of the system (the
545 which do not begin with `/' are interpreted as starting in the current
546 .I "working directory" ,
547 which is, by default, your
549 directory and can be changed dynamically by the
551 change directory command.
552 Such pathnames are said to be
554 to the working directory since they are found by starting
555 in the working directory and descending to lower levels of directories
558 of the pathname. If the pathname contains no slashes at all then the
559 file is contained in the working directory itself and the pathname is merely
560 the name of the file in this directory.
561 Absolute pathnames have no relation
562 to the working directory.
564 Most filenames consist of a number of alphanumeric characters and
566 In fact, all printing characters except `/' (slash) may appear in filenames.
567 It is inconvenient to have most non-alphabetic characters in filenames
568 because many of these have special meaning to the shell.
569 The character `.' (period) is not a shell-metacharacter and is often used
572 of a file name from the base of the name.
575 prog.c prog.o prog.errs prog.output
577 are four related files.
581 (a base portion being that part of the name that is left when a trailing
582 `.' and following characters which are not `.' are stripped off).
585 might be the source for a C program,
586 the file `prog.o' the corresponding object file,
588 `prog.errs' the errors resulting from a compilation of the program
590 `prog.output' the output of a run of the program.
592 If we wished to refer to all four of these files in a command, we could
597 This expression is expanded by the shell, before the command to which it is
598 an argument is executed, into a list of names which begin with `prog.'.
599 The character `*' here matches any sequence (including the empty sequence)
600 of characters in a file name.
601 The names which match are alphabetically sorted and placed in the
610 prog.c prog.errs prog.o prog.output
612 Note that the names are in sorted order here, and a different
613 order than we listed them above.
616 command receives four words as arguments, even though we only typed
617 one word as as argument directly.
618 The four words were generated by
619 .I "filename expansion"
620 of the one input word.
623 .I "filename expansion"
625 The character `?' matches any single character in a filename.
630 will echo a line of filenames; first those with one character names,
631 then those with two character names, and finally those with three
633 The names of each length will be independently sorted.
635 Another mechanism consists of a sequence of characters between `[' and `]'.
636 This metasequence matches any single character from the enclosed set.
645 in the example above.
646 We can also place two characters around a `\-' in this notation to denote
654 chap.1 chap.2 chap.3 chap.4 chap.5
657 This is shorthand for
661 and otherwise equivalent.
663 An important point to note is that if a list of argument words to
666 contains filename expansion syntax, and if this filename expansion syntax
667 fails to match any existing file names, then the shell considers this
668 to be an error and prints a diagnostic
672 and does not execute the command.
674 Another very important point is that files with the character `.' at the
675 beginning are treated specially.
676 Neither `*' or `?' or the `[' `]' mechanism will match it.
677 This prevents accidental matching of the filenames `.' and `..'
678 in the working directory which have special meaning to the system,
679 as well as other files such as
681 which are not normally
683 We will discuss the special role of the file
687 Another filename expansion mechanism gives access to the pathname of
690 directory of other users.
691 This notation consists of the character `~' (tilde) followed by another user's
693 For instance the word `~bill' would map to the pathname `/usr/bill'
694 if the home directory for `bill' was `/usr/bill'.
695 Since, on large systems, users may have login directories scattered over
696 many different disk volumes with different prefix directory names,
697 this notation provides a convenient way of accessing the files
700 A special case of this notation consists of a `~' alone, e.g. `~/mbox'.
701 This notation is expanded by the shell into the file `mbox' in your
703 directory, i.e. into `/usr/bill/mbox' for me on Ernie Co-vax, the UCB
704 Computer Science Department VAX machine, where this document was prepared.
705 This can be very useful if you have used
707 to change to another directory and have found a file you wish to
710 If I give the command
714 the shell will expand this command to
716 cp thatfile /usr/bill
718 since my home directory is /usr/bill.
720 There also exists a mechanism using the characters `{' and `}' for
721 abbreviating a set of words which have common parts but cannot
722 be abbreviated by the above mechanisms because they are not files,
723 are the names of files which do not yet exist,
724 are not thus conveniently described.
725 This mechanism will be described much later,
727 as it is used less frequently.
731 We have already seen a number of metacharacters used by the shell.
732 These metacharacters pose a problem in that we cannot use them directly
738 will not echo the character `*'.
739 It will either echo an sorted list of filenames in the
741 .I "working directory,"
742 or print the message `No match' if there are
743 no files in the working directory.
745 The recommended mechanism for placing characters which are neither numbers,
746 digits, `/', `.' or `\-' in an argument word to a command is to enclose
747 it with single quotation characters `\'', i.e.
751 There is one special character `!' which is used by the
753 mechanism of the shell and which cannot be
755 by placing it within `\'' characters.
756 It and the character `\'' itself can be preceded by a single `\e'
757 to prevent their special meaning.
766 These two mechanisms suffice to place any printing character into a word
767 which is an argument to a shell command. They can be combined, as in
775 since the first `\e' escaped the first `\'' and the `*' was enclosed
776 between `\'' characters.
780 When you are executing a command and the shell is
781 waiting for it to complete there are several ways
783 For instance if you type the command
787 the system will print a copy of a list of all users of the system
789 This is likely to continue for several minutes unless you stop it.
795 command by typing ^C on your terminal.*
797 *On some older Unix systems the \s-2DEL\s0 or \s-2RUBOUT\s0 key
798 has the same effect. "stty all" will tell you the INTR key value.
802 does not take any precautions to avoid or otherwise handle this signal
805 will cause it to terminate.
806 The shell notices that
808 has terminated and prompts you again with `% '.
809 If you hit \s-2INTERRUPT\s0 again, the shell will just
810 repeat its prompt since it handles \s-2INTERRUPT\s0 signals
811 and chooses to continue to execute commands rather than terminating
814 did, which would have the effect of logging you out.
816 Another way in which many programs terminate is when they get an end-of-file
817 from their standard input.
820 program in the first example above was terminated when we typed a ^D
821 which generates an end-of-file from the standard input.
822 The shell also terminates when it gets an end-of-file printing `logout';
823 \s-2UNIX\s0 then logs you off the system.
824 Since this means that typing too many ^D's can accidentally log us off,
825 the shell has a mechanism for preventing this.
828 option will be discussed in section 2.2.
830 If a command has its standard input redirected from a file, then it will
831 normally terminate when it reaches the end of this file.
834 mail bill < prepared.text
836 the mail command will terminate without our typing a ^D.
837 This is because it read to the end-of-file of our file
838 `prepared.text' in which we placed a message for `bill' with an editor program.
839 We could also have done
841 cat prepared.text \||\| mail bill
845 command would then have written the text through the pipe to the
846 standard input of the mail command.
849 command completed it would have terminated,
850 closing down the pipeline
853 command would have received an end-of-file from it and terminated.
854 Using a pipe here is more complicated than redirecting input
855 so we would more likely use the first form.
856 These commands could also have been stopped by sending an \s-2INTERRUPT\s0.
858 Another possibility for stopping a command is to suspend its execution
859 temporarily, with the possibility of continuing execution later. This is
860 done by sending a \s-2STOP\s0 signal via typing a ^Z.
861 This signal causes all commands running on the terminal
862 (usually one but more if a pipeline is executing) to become suspended.
863 The shell notices that the command(s) have been suspended, types
864 `Stopped' and then prompts for a new command.
865 The previously executing command has been suspended, but otherwise
866 unaffected by the \s-2STOP\s0 signal. Any other commands can be executed
867 while the original command remains suspended. The suspended command can
868 be continued using the
870 command with no arguments. The shell will then retype the command
871 to remind you which command is being continued, and cause the command
872 to resume execution. Unless any input files in use by the suspended
873 command have been changed in the meantime, the suspension has no effect
874 whatsoever on the execution of the command. This feature can be very useful
875 during editing, when you need to look at another file before continuing. An
876 example of command suspension follows.
879 Someone just copied a big file into my directory and its name is
888 [1] + Stopped mail harold
891 funnyfile. Do you know who did it?
896 In this example someone was sending a message to Harold and forgot the
897 name of the file he wanted to mention. The mail command was suspended
898 by typing ^Z. When the shell noticed that the mail program was
899 suspended, it typed `Stopped' and prompted for a new command. Then the
901 command was typed to find out the name of the file. The
903 command was run to find out which command was suspended. At this time the
905 command was typed to continue execution of the mail program. Input
906 to the mail program was then continued and ended with a ^D
907 which indicated the end of the message at which time the mail
908 program typed EOT. The
910 command will show which commands are suspended.
911 The ^Z should only be typed at the beginning of a line since
912 everything typed on the current line is discarded when a signal is sent
913 from the keyboard. This also happens on \s-2INTERRUPT\s0, and \s-2QUIT\s0
914 signals. More information on
915 suspending jobs and controlling them is given in
918 If you write or run programs which are not fully debugged then it may
919 be necessary to stop them somewhat ungracefully.
920 This can be done by sending them a \s-2QUIT\s0
921 signal, sent by typing a ^\e.
922 This will usually provoke the shell to produce a message like:
926 indicating that a file
927 `core' has been created containing information about the running program's
928 state when it terminated due to the \s-2QUIT\s0 signal.
929 You can examine this file yourself, or forward information to the
930 maintainer of the program telling him/her where the
934 If you run background commands (as explained in section 2.6) then these
935 commands will ignore \s-2INTERRUPT\s0 and \s-2QUIT\s0 signals at the
936 terminal. To stop them you must use the
938 command. See section 2.6 for an example.
940 If you want to examine the output of a command without having it move
941 off the screen as the output of the
945 command will, you can use the command
951 program pauses after each complete screenful and types `\-\-More\-\-'
952 at which point you can hit a space to get another screenful, a return
953 to get another line, a `?' to get some help on other commands, or a `q' to end the
955 program. You can also use more as a filter, i.e.
957 cat /etc/passwd | more
959 works just like the more simple more command above.
961 For stopping output of commands not involving
964 ^S key to stop the typeout. The typeout will resume when you
965 hit ^Q or any other key, but ^Q is normally used because
966 it only restarts the output and does not become input to the program
967 which is running. This works well on low-speed terminals, but at 9600
968 baud it is hard to type ^S and ^Q fast enough to paginate
969 the output nicely, and a program like
973 An additional possibility is to use the ^O flush output
974 character; when this character is typed, all output from the current
975 command is thrown away (quickly) until the next input read occurs
976 or until the next shell prompt. This can be used to allow a command
977 to complete without having to suffer through the output on a slow
978 terminal; ^O is a toggle, so flushing can be turned off by
979 typing ^O again while output is being flushed.
983 We have so far seen a number of mechanisms of the shell and learned a lot
984 about the way in which it operates.
985 The remaining sections will go yet further into the internals of the
986 shell, but you will surely want to try using the
987 shell before you go any further.
988 To try it you can log in to \s-2UNIX\s0 and type the following
989 command to the system:
993 Here `myname' should be replaced by the name you typed to
994 the system prompt of `login:' to get onto the system.
995 Thus I would use `chsh bill /bin/csh'.
997 You only have to do this once; it takes effect at next login.
999 You are now ready to try using
1002 Before you do the `chsh' command, the shell you are using when
1003 you log into the system is `/bin/sh'.
1004 In fact, much of the above discussion is applicable to `/bin/sh'.
1005 The next section will introduce many features particular to
1007 so you should change your shell to
1009 before you begin reading it.