.RP .TL An introduction to the C shell .br \s-2\fI(Revised for the Third Berkeley Distribution)\fP\s0 .AU William Joy .AI Computer Science Division .br Department of Electrical Engineering and Computer Science .br University of California, Berkeley .br Berkeley, California 94720 .AB .I Csh is a new command language interpreter for .UX systems. It incorporates good features of other shells and a .I history mechanism similar to the .I redo of \s-2INTERLISP\s0. While incorporating many features of other shells which make writing shell programs (shell scripts) easier, most of the features unique to .I csh are designed more for the interactive \s-2UNIX\s0 user. .PP \s-2UNIX\s0 users who have read a general introduction to the system will find a valuable basic explanation of the shell here. Simple terminal interaction with .I csh is possible after reading just the first section of this document. The second section describes the shells capabilities which you can explore after you have begun to become acquainted with the shell. Later sections introduce features which are useful, but not necessary for all users of the shell. .PP Back matter includes an appendix listing special characters of the shell and a glossary of terms and commands introduced in this manual. .AE .SH .if n .ND Introduction .PP A .I shell is a command language interpreter. .I Csh is the name of one particular command interpreter on \s-2UNIX\s0. The primary purpose of .I csh is to translate command lines typed at a terminal into system actions, such as invocation of other programs. .I Csh is a user program just like any you might write. Hopefully, .I csh will be a very useful program for you in interacting with the \s-2UNIX\s0 system. .PP In addition to this document, you will want to refer to a copy of the ``\s-2UNIX\s0 Programmers Manual.'' The .I csh documentation in the manual provides a full description of all features of the shell and is a final reference for questions about the shell. .PP Many words in this document are shown in .I italics. These are important words; names of commands, and words which have special meaning in discussing the shell and \s-2UNIX\s0. 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. .SH Acknowledgements .PP Numerous people have provided good input about previous versions of .I csh and aided in its debugging and in the debugging of its documentation. I would especially like to thank Michael Ubell who made the crucial observation that history commands 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. .br .bp .NH Terminal usage of the shell .NH 2 The basic notion of commands .PP A .I shell in \s-2UNIX\s0 acts mostly as a medium through which other .I commands are invoked. While it has a set of .I builtin commands which it performs directly, most useful commands are, in fact, external to the shell. The shell is thus distinguished from the command interpreters of other systems both by the fact that it is just a user program, and by the fact that it is used almost exclusively as a mechanism for invoking other programs. .PP Commands in the \s-2UNIX\s0 system expect a list of strings or .I words as arguments. Thus the command .DS mail bill .DE consists of two words. The first word .I mail 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 run it for you. It will look in a number of .I directories for a file with the name .I mail which is expected to contain the mail program. .PP The rest of the words of the command are given to the command itself to execute. In this case we specified also the word .I bill which is interpreted by the .I mail program to be the name of a user to whom mail is to be sent. In normal terminal usage we might use the .I mail command as follows. .DS % 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 % .DE .PP Here we typed a message to send to .I bill and ended this message with a control-d which sent an end-of-file to the mail program. 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. .PP 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 .I mail program with argument .I bill and went dormant waiting for it to complete. The mail program then read input from our terminal until we signalled an end-of-file after which the shell noticed that mail had completed and signaled us that it was ready to read from the terminal again by printing another `% ' prompt. .PP This is the essential pattern of all interaction with \s-2UNIX\s0 through the shell. A complete command is typed at the terminal, the shell executes the command and when this execution completes prompts for a new command. If you run the editor for an hour, the shell will patiently wait for you to finish editing and obediently prompt you again whenever you finish editing. .PP An example of a useful command you can execute now is the .I tset command, which sets the default .I erase and .I kill characters on your terminal \- the erase character erases the last character you typed and the kill character erases the entire line you have entered so far. By default, the erase character is `#' and the kill character is `@'. Most people who use \s-2CRT\s0 displays prefer to use the backspace (control-h) character as their erase character since it is then easier to see what you have typed so far. You can make this be true by typing .DS tset \-e .DE which tells the program .I tset to set the erase character, and its default setting for this character is a backspace. .NH 2 Flag arguments .PP A useful notion in \s-2UNIX\s0 is that of a .I flag argument. While many arguments to commands specify file names or user names some arguments rather specify an optional capability of the command which you wish to invoke. By convention, such arguments begin with the character `\-'. Thus the command .DS ls .DE will produce a list of the files in the current directory. The option .I \-s is the size option, and .DS ls \-s .DE causes .I ls to also give, for each file the size of the file in blocks of 512 characters. The manual page for each command in the \s-2UNIX\s0 programmers manual gives the available options for each command. The .I ls command has a large number of useful and interesting options. Most other commands have either no options or only one or two options. It is hard to remember options of commands which are not used very frequently, so most \s-2UNIX\s0 utilities perform only one or two functions rather than having a large number of hard to remember options. .NH 2 Output to files .PP Many commands may read input or write output to files rather than simply taking input and output from the terminal. Each such command could take special words as arguments indicating where the output is to go. It is simpler, and usually sufficient, to connect these commands to files to which they wish to write, within the shell itself, and just before they are executed. .PP Thus suppose we wish to save the current date in a file called `now'. The command .DS date .DE will print the current date on our terminal. This is because our terminal is the default .I "standard output" for the date command and the date command prints the date on its standard output. The shell lets us redirect the .I "standard output" of a command through a notation using the .I metacharacter `>' and the name of the file where output is to be placed. Thus the command .DS date > now .DE runs the .I date command in an environment where its standard output is the file `now' rather than our terminal. Thus this command places the current date and time in the file `now'. It is important to know that the .I date command was unaware that its output was going to a file rather than to our terminal. The shell performed this .I redirection before the command began executing. .PP One other thing to note here is that the file `now' need not have existed before the .I date command was executed; 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 .I noclobber exists to prevent this from happening accidentally; it is discussed in section 2.2. .PP 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.* .FS *Note that if your erase character is a `#', you will have to precede the `#' with a `\e'. The fact that the `#' character is the old (pre-\s-2CRT\s0) 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 \s-2CRT\s0, your erase character should be a control-h, as we demonstrated in section 1.1 how this could be set up. .FE The system will remove such files after a couple of days, or sooner if file space becomes very tight. Thus, in running the .I date command above, we don't really want to save the output forever, so we would more likely do .DS date > #now .DE .NH 2 Metacharacters in the shell .PP The shell has a large number of special characters (like `>') which indicate special functions. We say that these notations have .I syntactic and .I semantic meaning to the shell. In general, most characters which are neither letters nor digits have special meaning to the shell. We shall shortly learn a means of .I quotation which allows us to create words which contain .I metacharacters and to thus work without constantly worrying about whether certain characters are metacharacters. .PP Note that the shell is only reading input when it has prompted with `% '. Thus metacharacters will normally have effect only then. We need not worry about placing shell metacharacters in a letter we are sending via .I mail. .NH 2 Input from files; pipelines .PP We learned above how to route the standard output of a command to a file. It is also possible to route the standard input of a command from a file. This is not often necessary since most commands will read from a file name given as argument. We can give the command .DS sort < data .DE to run the .I sort command with standard input, where the command normally reads, from the file `data'. We would more likely say .DS sort data .DE letting the .I sort command open the file `data' for input itself since this is less to type. .PP We should note that if we just typed .DS sort .DE then the sort program would sort lines from its .I "standard input." Since we did not .I redirect the standard input, it would sort lines as we typed them on the terminal until we typed a control-d to generate an end-of-file. .PP A most useful capability is the ability to combine the standard output of one command with the standard input of the next, i.e. to run the commands in a sequence known as a .I pipeline. For instance the command .DS ls \-s .DE normally produces a list of the files in our directory with the size of each in blocks of 512 characters. If we are interested in learning which of our files is largest we may wish to have this sorted by size rather than by name, which is the default way in which .I ls sorts. We could look at the many options of .I ls to see if there was an option to do this but would eventually discover that there is not. Instead we can use a couple of simple options of the .I sort command, combining it with .I ls to get what we want. .PP The .I \-n option of sort specifies a numeric sort rather than an alphabetic sort. Thus .DS ls \-s | sort \-n .DE specifies that the output of the .I ls command run with the option .I \-s is to be .I piped to the command .I sort run with the numeric sort option. This would give us a sorted list of our files by size, but with the smallest first. We could then use the .I \-r reverse sort option and the .I head command in combination with the previous command doing .DS ls \-s | sort \-n \-r | head \-5 .DE Here we have taken a list of our files sorted alphabetically, each with the size in blocks. We have run this to the standard input of the .I sort command asking it to sort numerically in reverse order (largest first). This output has then been run into the command .I head which gives us the first few lines out. In this case we have asked .I head for the first 5 lines. Thus this command gives us the names and sizes of our 5 largest files. .PP The metanotation introduced above is called the .I pipe mechanism. Commands separated by `\||\|' characters are connected together by the shell and the output of each is run into the 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 given later when we discuss the history mechanism; one important use of pipes which is illustrated there is in the routing of information to the line printer. .NH 2 Filenames .PP Many commands to be executed will need the names of files as arguments. \s-2UNIX\s0 pathnames consist of a number of components separated by `/'. Each component except the last names a directory in which the next component resides. Thus the pathname .DS /etc/motd .DE specifies a file in the directory `etc' which is a subdirectory of the .I root directory `/'. Within this directory the file named is `motd' which stands for `message of the day'. Filenames which do not begin with `/' are interpreted starting at the current .I working directory. This directory is, by default, your .I home directory and can be changed dynamically by the .I chdir change directory command. .PP Most filenames consist of a number of alphanumeric characters and `.'s. In fact, all printing characters except `/' 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 `.' is not a shell-metacharacter and is often used as the prefix with an .I extension of a base name. Thus .DS prog.c prog.o prog.errs prog.output .DE are four related files. They share a .I root portion of a name (a root portion being that part of the name that is left when a trailing `.' and following characters which are not `.' are stripped off). The file `prog.c' might be the source for a C program, the file `prog.o' the corresponding 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. .PP If we wished to refer to all four of these files in a command, we could use the metanotation .DS prog.* .DE This word is expanded by the shell, before the command to which it is an argument is executed, into a list of names which begin with `prog.'. The character `*' here matches any sequence (including the empty sequence) of characters in a file name. The names which match are sorted into the argument list to the command alphabetically. Thus the command .DS echo prog.* .DE will echo the names .DS prog.c prog.errs prog.o prog.output .DE Note that the names are in lexicographic order here, and a different order than we listed them above. The .I echo command receives four words as arguments, even though we only typed one word as as argument directly. The four words were generated by filename expansion of the metasyntax in the one input word. .PP Other metanotations for .I "filename expansion" are also available. The character `?' matches any single character in a filename. Thus .DS echo ? \|?? \|??? .DE will echo a line of 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 lexicographically sorted. .PP Another mechanism consists of a sequence of characters between `[' and `]'. This metasequence matches any single character from the enclosed set. Thus .DS prog.[co] .DE will match .DS prog.c prog.o .DE in the example above. We can also place two characters astride a `\-' in this notation to denote a range. Thus .DS chap.[1\-5] .DE might match files .DS chap.1 chap.2 chap.3 chap.4 chap.5 .DE if they existed. This is shorthand for .DS chap.[12345] .DE and otherwise equivalent. .PP An important point to note is that if a list of argument words to a command (an .I "argument list)" contains filename expansion syntax, and if this filename expansion syntax fails to match any existing file names, then the shell considers this to be an error and prints a diagnostic .DS No match. .DE .PP Another very important point is that the character `.' at the beginning of a filename is treated specially. Neither `*' or `?' or the `[' `]' mechanism will match it. This prevents accidental matching of the filenames `.' and `..' in the current directory which have special meaning to the system, as well as other files such as .I \&.cshrc which are not normally visible. We will discuss the special role of the file .I \&.cshrc later. .PP Another filename expansion mechanism gives access to the pathname of the .I home directory of other users. This notation consists of the character `~' followed by another users login name. For instance the word `~bill' would map to the pathname `/usr/bill' if the home directory for `bill' was in the directory `/usr/bill'. Since, on large systems, users may have login directories scattered over many different disk volumes with different prefix directory names, this notation provides a reliable way of accessing the files of other users. .PP A special case of this notation consists of a `~' alone, e.g. `~/mbox'. This notation is expanded by the shell into the file `mbox' in your .I home directory, 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 .I chdir to change to another users directory and have found a file you wish to copy using .I cp. You can do .DS cp thatfile ~ .DE which will be expanded by the shell to .DS cp thatfile /usr/bill .DE e.g., which the copy command will interpret as a request to make a copy of `thatfile' in the directory `/usr/bill'. The `~' notation doesn't, by itself, force named files to exist. This is useful, for example, when using the .I cp command, e.g. .DS cp thatfile ~/saveit .DE .PP There also exists a mechanism using the characters `{' and `}' for abbreviating a set of word 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 exist, are not thus conveniently described. This mechanism will be described much later, in section 4.1, as it is used less frequently. .NH 2 Quotation .PP We have already seen a number of metacharacters used by the shell. These metacharacters pose a problem in that we cannot use them directly as parts of words. Thus the command .DS echo * .DE will not echo the character `*'. It will either echo an sorted list of filenames in the current directory, or print the message `No match' if there are no files in the current directory. .PP The recommended mechanism for placing characters which are neither numbers, digits, `/', `.' or `\-' in an argument word to a command is to enclose it with single quotation characters `\'', i.e. .DS echo \'*\' .DE There is one special character `!' which is used by the .I history mechanism of the shell and which cannot be .I escaped by placing it within \` characters. It and the character `\'' itself can be preceded by a single `\e' to prevent their special meaning. Thus .DS echo \e\'\e! .DE prints .DS \'! .DE These two mechanisms suffice to place any printing character into a word which is an argument to a shell command. They can be combined, as in .DS echo \e\'\'*\' .DE which prints .DS \'* .DE .NH 2 Terminating commands .PP When you are running a command from the shell and the shell is dormant waiting for it to complete there are a couple of ways in which you can force such a command to stop. For instance if you type the command .DS cat /etc/passwd .DE the system will print a copy of a list of all users of the system on your terminal. This is likely to continue for several minutes unless you stop it. You can send an \s-2INTERRUPT\s0 signal to the .I cat command by hitting the \s-2DEL\s0 or \s-2RUBOUT\s0 key on your terminal. Actually, hitting this key sends this \s-2INTERRUPT\s0 signal to all programs running on your terminal, including your shell. The shell normally ignores such signals however, so that the only program affected by the \s-2INTERRUPT\s0 will be .I cat. Since .I cat does not take any precautions to catch this signal the \s-2INTERRUPT\s0 will cause it to terminate. The shell notices that .I cat has died and prompts you again with `% '. If you hit \s-2INTERRUPT\s0 again, the shell will just repeat its prompt since it catches \s-2INTERRUPT\s0 signals and chooses to continue to execute commands rather than going away like .I cat did, which would have the effect of logging you out. .PP Another way in which many programs terminate is when they get an end-of-file from their standard input. Thus the .I mail program in the first example above was terminated when we hit a control-d which generates and end-of-file from the standard input. The shell also terminates when it gets an end-of-file printing `logout'; \s-2UNIX\s0 then logs you off the system. Since this means that typing too many control-d's can accidentally log us off, the shell has a mechanism for preventing this. This .I ignoreeof option will be discussed in section 2.2. .PP If a command has its standard input redirected from a file, then it will normally terminate when it reaches the end of this file. Thus if we execute .DS mail bill < prepared.text .DE the mail command will terminate without our typing a control-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. We could also have done .DS cat prepared.text \||\| mail bill .DE since the .I cat command would then have written the text through the pipe to the standard input of the mail command. When the .I cat command completed it would have terminated, closing down the pipeline and the .I mail command would have received an end-of-file from it and terminated. Using a pipe here is more complicated than redirecting input so we would more likely use the first form. These commands could also have been stopped by sending an \s-2INTERRUPT\s0. .PP 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 \s-2QUIT\s0 signal, generated by a control-\e. This will usually provoke the shell to produce a message like: .DS a.out: Quit \-\- Core dumped .DE indicating that a file `core' has been created containing information about the program `a.out's state when it ran amuck. You can examine this file yourself, or forward information to the maintainer of the program telling him/her where the .I "core file" is. .PP If you run background commands (as explained in section 2.6) then these commands will ignore \s-2INTERRUPT\s0 and \s-2QUIT\s0 signals at the terminal. To stop them you must use the .I kill program. See section 2.6 for an example. .PP If you want to examine the output of a command without having it shoot off the screen as the output of the .DS cat /etc/passwd .DE command will, you can use the command .DS more /etc/passwd .DE The .I more 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, or a `q' to end the .I more program. You can also use more as a filter, i.e. .DS cat /etc/passwd | more .DE works just like the more simple more command above. .PP For stopping output of commands not involving more you can use the control-s key to stop the typeout. The typeout will resume when you hit control-q or any other key, but control-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 control-s and control-q fast enough to paginate the output nicely, and a program like .I more is usually used. .NH 2 What now? .PP We have so far seen a number of mechanisms of the shell and learned a lot about the way in which it operates. The remaining sections will go yet further into the internals 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 \s-2UNIX\s0 and type the following command to the system: .DS chsh myname /bin/csh .DE 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'. .B You only have to do this once; it takes effect at next login. .R You are now ready to try using .I csh. .PP 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 introduce many features particular to .I csh so you should change your shell to .I csh before you begin reading it. .bp