Sync some manuals from bin & sbin with NetBSD-8
[minix.git] / bin / csh / USD.doc / csh.2
blob803434b1929e41dcb34bdb8eeac4c26d80291fa4
1 .\"     $NetBSD: csh.2,v 1.7 2003/08/07 09:05:08 agc Exp $
2 .\"
3 .\" Copyright (c) 1980, 1993
4 .\"     The Regents of the University of California.  All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
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.
17 .\"
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
28 .\" SUCH DAMAGE.
29 .\"
30 .\"     @(#)csh.2       8.1 (Berkeley) 6/8/93
31 .\"
32 .nr H1 1
33 .NH
34 Details on the shell for terminal users
35 .NH 2
36 Shell startup and termination
37 .PP
38 When you login, the shell is started by the system in your
39 .I home
40 directory and begins by reading commands from a file
41 .I \&.cshrc
42 in this directory.
43 All shells which you may start during your terminal session will
44 read from this file.
45 We will later see what kinds of commands are usefully placed there.
46 For now we need not have this file and the shell does not complain about
47 its absence.
48 .PP
50 .I "login shell" ,
51 executed after you login to the system,
52 will, after it reads commands from
53 .I \&.cshrc,
54 read commands from a file
55 .I \&.login
56 also in your home directory.
57 This file contains commands which you wish to do each time you login
58 to the \s-2UNIX\s0 system.
60 .I \&.login
61 file looks something like:
62 .DS
63 set ignoreeof
64 set mail=(/var/mail/bill)
65 echo "${prompt}users" ; users
66 alias ts \e
67         \'set noglob ; eval \`tset \-s \-m dialup:c100rv4pna \-m plugboard:?hp2621nl \!*\`\';
68 ts; stty intr ^C kill ^U crt
69 set time=15 history=10
70 msgs \-f
71 if (\-e $mail) then
72         echo "${prompt}mail"
73         mail
74 endif
75 .DE
76 .PP
77 This file contains several commands to be executed by \s-2UNIX\s0
78 each time I login.
79 The first is a
80 .I set
81 command which is interpreted directly by the shell.  It sets the shell
82 variable
83 .I ignoreeof
84 which causes the shell to not log me off if I hit ^D.  Rather,
85 I use the
86 .I logout
87 command to log off of the system.
88 By setting the
89 .I mail
90 variable, I ask the shell to watch for incoming mail to me.  Every 5 minutes
91 the shell looks for this file and tells me if more mail has arrived there.
92 An alternative to this is to put the command
93 .DS
94 biff y
95 .DE
96 in place of this
97 .I set;
98 this will cause me to be notified immediately when mail arrives, and to
99 be shown the first few lines of the new message.
101 Next I set the shell variable `time' to `15' causing the shell to automatically
102 print out statistics lines for commands which execute for at least 15 seconds
103 of \s-2CPU\s+2 time.  The variable `history' is set to 10 indicating that
104 I want the shell to remember the last 10 commands I type in its
105 .I "history list" ,
106 (described later).
108 I create an
109 .I alias
110 ``ts'' which executes a
111 \fItset\fR\|(1) command setting up the modes of the terminal.
112 The parameters to
113 .I tset
114 indicate the kinds of terminal which I usually use when not on a hardwired
115 port.  I then execute ``ts'' and also use the
116 .I stty
117 command to change the interrupt character to ^C and the line kill
118 character to ^U.
120 I then run the `msgs' program, which provides me with any
121 system messages which I have not seen before; the `\-f' option here prevents
122 it from telling me anything if there are no new messages.
123 Finally, if my mailbox file exists, then I run the `mail' program to
124 process my mail.
126 When the `mail' and `msgs' programs finish, the shell will finish
127 processing my
128 .I \&.login
129 file and begin reading commands from the terminal, prompting for each with
130 `% '.
131 When I log off (by giving the
132 .I logout
133 command) the shell
134 will print `logout' and execute commands from the file `.logout'
135 if it exists in my home directory.
136 After that the shell will terminate and \s-2UNIX\s0 will log
137 me off the system.
138 If the system is not going down, I will receive a new login message.
139 In any case, after the `logout' message the shell is committed to terminating
140 and will take no further input from my terminal.
141 .NH 2
142 Shell variables
144 The shell maintains a set of
145 .I variables.
146 We saw above the variables
147 .I history
149 .I time
150 which had values `10' and `15'.
151 In fact, each shell variable has as value an array of
152 zero or more
153 .I strings.
154 Shell variables may be assigned values by the set command.  It has
155 several forms, the most useful of which was given above and is
157 set name=value
160 Shell variables may be used to store values which are to
161 be used in commands later through a substitution mechanism.
162 The shell variables most commonly referenced are, however, those which the
163 shell itself refers to.
164 By changing the values of these variables one can directly affect the
165 behavior of the shell.
167 One of the most important variables is the variable
168 .I path.
169 This variable contains a sequence of directory names where the shell
170 searches for commands.
172 .I set
173 command with no arguments
174 shows the value of all variables currently defined (we usually say
175 .I set)
176 in the shell.
177 The default value for path will be shown by
178 .I set
179 to be
181 % set
182 .ta .75i
183 argv    ()
184 cwd     /usr/bill
185 home    /usr/bill
186 path    (. /usr/ucb /bin /usr/bin)
187 prompt  %
188 shell   /bin/csh
189 status  0
190 term    c100rv4pna
191 user    bill
193 .so tabs
195 This output indicates that the variable path points to the current
196 directory `.' and then `/usr/ucb', `/bin' and `/usr/bin'.
197 Commands which you may write might be in `.' (usually one of
198 your directories).
199 Commands developed at Berkeley, live in `/usr/ucb'
200 while commands developed at Bell Laboratories live in `/bin' and `/usr/bin'.
202 A number of locally developed programs on the system live in the directory
203 `/usr/local'.
204 If we wish that all shells which we invoke to have
205 access to these new programs we can place the command
207 set path=(. /usr/ucb /bin /usr/bin /usr/local)
209 in our file
210 .I \&.cshrc
211 in our home directory.
212 Try doing this and then logging out and back in and do
216 again to see that the value assigned to
217 .I path
218 has changed.
219 .FS \(dg
220 Another directory that might interest you is /usr/new, which contains
221 many useful user-contributed programs provided with Berkeley Unix.
224 One thing you should be aware of is that the shell examines each directory
225 which you insert into your path and determines which commands are contained
226 there.  Except for the current directory `.', which the shell treats specially,
227 this means that if commands are added to a directory in your search path after
228 you have started the shell, they will not necessarily be found by the shell.
229 If you wish to use a command which has been added in this way, you should
230 give the command
232 rehash
234 to the shell, which will cause it to recompute its internal table of command
235 locations, so that it will find the newly added command.
236 Since the shell has to look in the current directory `.' on each command,
237 placing it at the end of the path specification usually works equivalently
238 and reduces overhead.
240 Other useful built in variables are the variable
241 .I home
242 which shows your home directory,
243 .I cwd
244 which contains your current working directory,
245 the variable
246 .I ignoreeof
247 which can be set in your
248 .I \&.login
249 file to tell the shell not to exit when it receives an end-of-file from
250 a terminal (as described above).
251 The variable `ignoreeof'
252 is one of several variables which the shell does not care about the
253 value of, only whether they are
254 .I set
256 .I unset.
257 Thus to set this variable you simply do
259 set ignoreeof
261 and to unset it do
263 unset ignoreeof
265 These give the variable `ignoreeof' no value, but none is desired or required.
267 Finally, some other built-in shell variables of use are the
268 variables
269 .I noclobber
271 .I mail.
272 The metasyntax
274 > filename
276 which redirects the standard output of a command
277 will overwrite and destroy the previous contents of the named file.
278 In this way you may accidentally overwrite a file which is valuable.
279 If you would prefer that the shell not overwrite files in this
280 way you can
282 set noclobber
284 in your
285 .I \&.login
286 file.
287 Then trying to do
289 date > now
291 would cause a diagnostic if `now' existed already.
292 You could type
294 date >!  now
296 if you really wanted to overwrite the contents of `now'.
297 The `>!' is a special metasyntax indicating that clobbering the
298 file is ok.\(dg
300 \(dgThe space between the `!' and the word `now' is critical here, as `!now'
301 would be an invocation of the
302 .I history
303 mechanism, and have a totally different effect.
305 .NH 2
306 The shell's history list
308 The shell can maintain a
309 .I "history list"
310 into which it places the words
311 of previous commands.
312 It is possible to use a notation to reuse commands or words
313 from commands in forming new commands.
314 This mechanism can be used to repeat previous commands or to
315 correct minor typing mistakes in commands.
317 The following figure gives a sample session involving typical usage of the
318 history mechanism of the shell.
321 % cat bug.c
322 main()
325         printf("hello);
327 % cc !$
328 cc bug.c
329 "bug.c", line 4: newline in string or char constant
330 "bug.c", line 5: syntax error
331 % ed !$
332 ed bug.c
334 4s/);/"&/p
335         printf("hello");
339 % !c
340 cc bug.c
341 % a.out
342 hello% !e
343 ed bug.c
345 4s/lo/lo\e\en/p
346         printf("hello\en");
350 % !c \-o bug
351 cc bug.c \-o bug
352 % size a.out bug
353 a.out: 2784+364+1028 = 4176b = 0x1050b
354 bug: 2784+364+1028 = 4176b = 0x1050b
355 % ls \-l !*
356 ls \-l a.out bug
357 \(mirwxr\(mixr\(mix 1 bill       3932 Dec 19 09:41 a.out
358 \(mirwxr\(mixr\(mix 1 bill       3932 Dec 19 09:42 bug
359 % bug
360 hello
361 % num bug.c | spp
362 spp: Command not found.
363 % ^spp^ssp
364 num bug.c | ssp
365     1   main()
366     3   {
367     4           printf("hello\en");
368     5   }
369 % !! | lpr
370 num bug.c | ssp | lpr
374 In this example we have a very simple C program which has a bug (or two)
375 in it in the file `bug.c', which we `cat' out on our terminal.  We then
376 try to run the C compiler on it, referring to the file again as `!$',
377 meaning the last argument to the previous command.  Here the `!' is the
378 history mechanism invocation metacharacter, and the `$' stands for the last
379 argument, by analogy to `$' in the editor which stands for the end of the line.
380 The shell echoed the command, as it would have been typed without use of
381 the history mechanism, and then executed it.
382 The compilation yielded error diagnostics so we now run the editor on the
383 file we were trying to compile, fix the bug, and run the C compiler again,
384 this time referring to this command simply as `!c', which repeats the last
385 command which started with the letter `c'.  If there were other
386 commands starting with `c' done recently we could have said `!cc' or even
387 `!cc:p' which would have printed the last command starting with `cc'
388 without executing it.
390 After this recompilation, we ran the resulting `a.out' file, and then
391 noting that there still was a bug, ran the editor again.  After fixing
392 the program we ran the C compiler again, but tacked onto the command
393 an extra `\-o bug' telling the compiler to place the resultant binary in
394 the file `bug' rather than `a.out'.  In general, the history mechanisms
395 may be used anywhere in the formation of new commands and other characters
396 may be placed before and after the substituted commands.
398 We then ran the `size' command to see how large the binary program images
399 we have created were, and then an `ls \-l' command with the same argument
400 list, denoting the argument list `\!*'.
401 Finally we ran the program `bug' to see that its output is indeed correct.
403 To make a numbered listing of the program we ran the `num' command on the file `bug.c'.
404 In order to compress out blank lines in the output of `num' we ran the
405 output through the filter `ssp', but misspelled it as spp.  To correct this
406 we used a shell substitute, placing the old text and new text between `^'
407 characters.  This is similar to the substitute command in the editor.
408 Finally, we repeated the same command with `!!', but sent its output to the
409 line printer.
411 There are other mechanisms available for repeating commands.  The
412 .I history
413 command prints out a number of previous commands with numbers by which
414 they can be referenced.  There is a way to refer to a previous command
415 by searching for a string which appeared in it, and there are other,
416 less useful, ways to select arguments to include in a new command.
417 A complete description of all these mechanisms
418 is given in the C shell manual pages in the \s-2UNIX\s0 Programmer's Manual.
419 .NH 2
420 Aliases
422 The shell has an
423 .I alias
424 mechanism which can be used to make transformations on input commands.
425 This mechanism can be used to simplify the commands you type,
426 to supply default arguments to commands,
427 or to perform transformations on commands and their arguments.
428 The alias facility is similar to a macro facility.
429 Some of the features obtained by aliasing can be obtained also
430 using shell command files, but these take place in another instance
431 of the shell and cannot directly affect the current shells environment
432 or involve commands such as
433 .I cd
434 which must be done in the current shell.
436 As an example, suppose that there is a new version of the mail program
437 on the system called `newmail'
438 you wish to use, rather than the standard mail program which is called
439 `mail'.
440 If you place the shell command
442 alias mail newmail
444 in your
445 .I \&.cshrc
446 file, the shell will transform an input line of the form
448 mail bill
450 into a call on `newmail'.
451 More generally, suppose we wish the command `ls' to always show
452 sizes of files, that is to always do `\-s'.
453 We can do
455 alias ls ls \-s
457 or even
459 alias dir ls \-s
461 creating a new command syntax `dir'
462 which does an `ls \-s'.
463 If we say
465 dir ~bill
467 then the shell will translate this to
469 ls \-s /mnt/bill
472 Thus the
473 .I alias
474 mechanism can be used to provide short names for commands,
475 to provide default arguments,
476 and to define new short commands in terms of other commands.
477 It is also possible to define aliases which contain multiple
478 commands or pipelines, showing where the arguments to the original
479 command are to be substituted using the facilities of the
480 history mechanism.
481 Thus the definition
483 alias cd \'cd \e!* ; ls \'
485 would do an
486 .I ls
487 command after each change directory
488 .I cd
489 command.
490 We enclosed the entire alias definition in `\'' characters to prevent
491 most substitutions from occurring and the character `;' from being
492 recognized as a metacharacter.
493 The `!' here is escaped with a `\e' to prevent it from being interpreted
494 when the alias command is typed in.
495 The `\e!*' here substitutes the entire argument list to the pre-aliasing
496 .I cd
497 command, without giving an error if there were no arguments.
498 The `;' separating commands is used here
499 to indicate that one command is to be done and then the next.
500 Similarly the definition
502 alias whois \'grep \e!^ /etc/passwd\'
504 defines a command which looks up its first argument in the password file.
506 .B Warning:
507 The shell currently reads the
508 .I \&.cshrc
509 file each time it starts up.  If you place a large number of commands
510 there, shells will tend to start slowly.  A mechanism for saving the shell
511 environment after reading the \fI\&.cshrc\fR file and quickly restoring it is
512 under development, but for now you should try to limit the number of
513 aliases you have to a reasonable number... 10 or 15 is reasonable,
514 50 or 60 will cause a noticeable delay in starting up shells, and make
515 the system seem sluggish when you execute commands from within the editor
516 and other programs.
517 .NH 2
518 More redirection; >> and >&
520 There are a few more notations useful to the terminal user
521 which have not been introduced yet.
523 In addition to the standard output, commands also have a
524 .I "diagnostic output"
525 which is normally directed to the terminal even when the standard output
526 is redirected to a file or a pipe.
527 It is occasionally desirable to direct the diagnostic output along with
528 the standard output.
529 For instance if you want to redirect the output of a long running command
530 into a file and wish to have a record of any error diagnostic it produces
531 you can do
533 command >& file
535 The `>&' here tells the shell to route both the diagnostic output and the
536 standard output into `file'.
537 Similarly you can give the command
539 command |\|& lpr
541 to route both standard and diagnostic output through the pipe
542 to the line printer daemon
543 .I lpr.\(dd
545 \(dd A command of the form
547 .ti +5
548 command >&! file
550 exists, and is used when
551 .I noclobber
552 is set and
553 .I file
554 already exists.
557 Finally, it is possible to use the form
559 command >> file
561 to place output at the end of an existing file.\(dg
563 \(dg If
564 .I noclobber
565 is set, then an error will result if
566 .I file
567 does not exist, otherwise the shell will create
568 .I file
569 if it doesn't exist.
570 A form
572 .ti +5
573 command >>! file
575 makes it not be an error for file to not exist when
576 .I noclobber
577 is set.
579 .NH 2
580 Jobs; Background, Foreground, or Suspended
582 When one or more commands
583 are typed together as a pipeline or as a sequence of commands separated by
584 semicolons, a single
585 .I job
586 is created by the shell consisting of these commands together as a unit.
587 Single commands without pipes or semicolons create the simplest jobs.
588 Usually, every line typed to the shell creates a job.
589 Some lines that create jobs (one per line) are
591 sort < data
592 ls \-s | sort \-n | head \-5
593 mail harold
596 If the metacharacter `&' is typed
597 at the end of the commands, then the job is started as a
598 .I background
599 job.  This means that the shell does not wait for it to complete but
600 immediately prompts and is ready for another command.  The job runs
601 .I "in the background"
602 at the same time that normal jobs, called
603 .I foreground
604 jobs, continue to be read and executed by the shell one at a time.
605 Thus
607 du > usage &
609 would run the
610 .I du
611 program, which reports on the disk usage of your working directory (as well as
612 any directories below it), put the output into the file `usage' and return
613 immediately with a prompt for the next command without out waiting for
614 .I du
615 to finish.  The
616 .I du
617 program would continue executing in the background
618 until it finished, even though you can type and execute more commands in the
619 mean time.
620 When a background
621 job terminates, a message is typed by the shell just before the next prompt
622 telling you that the job has completed.
623 In the following example the
624 .I du
625 job finishes sometime during the
626 execution of the
627 .I mail
628 command and its completion is reported just before
629 the prompt after the
630 .I mail
631 job is finished.
633 % du > usage &
634 [1] 503
635 % mail bill
636 How do you know when a background job is finished?
638 .ta 1.75i
639 [1] \- Done     du > usage
641 .so tabs
643 If the job did not terminate normally the `Done' message might say
644 something else like `Killed'.
645 If you want the
646 terminations of background jobs to be reported at the time they occur
647 (possibly interrupting the output of other foreground jobs), you can set
649 .I notify
650 variable.  In the previous example this would mean that the
651 `Done' message might have come right in the middle of the message to
652 Bill.
653 Background jobs are unaffected by any signals from the keyboard like
654 the \s-2STOP\s0, \s-2INTERRUPT\s0, or \s-2QUIT\s0 signals mentioned earlier.
656 Jobs are recorded in a table inside the shell until they terminate.
657 In this table, the shell remembers the command names, arguments and the
658 .I "process numbers"
659 of all commands in the job as well as the working directory where the job was
660 started.
661 Each job in the table is either running
662 .I "in the foreground"
663 with the shell waiting for it to terminate, running
664 .I "in the background,"
666 .I suspended.
667 Only one job can be running in the foreground at one time, but several
668 jobs can be suspended or running in the background at once.  As each job
669 is started, it is assigned a small identifying
670 number called the
671 .I "job number"
672 which can be used later to refer to the job in the commands described below.
673 Job numbers remain
674 the same until the job terminates and then are re-used.
676 When a job is started in the backgound using `&', its number, as well
677 as the process numbers of all its (top level) commands, is typed by the shell
678 before prompting you for another command. For example,
680 % ls \-s | sort \-n > usage &
681 [2] 2034 2035
684 runs the `ls' program with the `\-s' options, pipes this output into
685 the `sort' program with the `\-n' option which puts its output into the
686 file `usage'.
687 Since the `&' was at the end of the line, these two programs were started
688 together as a background job.  After starting the job, the shell prints
689 the job number in brackets (2 in this case) followed by the process number
690 of each program started in the job.  Then the shell immediates prompts for
691 a new command, leaving the job running simultaneously.
693 As mentioned in section 1.8, foreground jobs become
694 .I suspended
695 by typing ^Z
696 which sends a \s-2STOP\s0 signal to the currently running
697 foreground job.  A background job can become suspended by using the
698 .I stop
699 command described below.  When jobs are suspended they merely stop
700 any further progress until started again, either in the foreground
701 or the backgound.  The shell notices when a job becomes stopped and
702 reports this fact, much like it reports the termination of background jobs.
703 For foreground jobs this looks like
705 % du > usage
707 Stopped
710 `Stopped' message is typed by the shell when it notices that the
711 .I du
712 program stopped.
713 For background jobs, using the
714 .I stop
715 command, it is
717 % sort usage &
718 [1] 2345
719 % stop %1
720 .ta 1.75i
721 [1] + Stopped (signal)  sort usage
723 .so tabs
725 Suspending foreground jobs can be very useful when you need to temporarily
726 change what you are doing (execute other commands) and then return to
727 the suspended job.  Also, foreground jobs can be suspended and then
728 continued as background jobs using the
729 .I bg
730 command, allowing you to continue other work and
731 stop waiting for the foreground job to finish.  Thus
733 % du > usage
735 Stopped
736 % bg
737 [1] du > usage &
740 starts `du' in the foreground, stops it before it finishes, then continues
741 it in the background allowing more foreground commands to be executed.
742 This is especially helpful
743 when a foreground job ends up taking longer than you expected and you
744 wish you had started it in the backgound in the beginning.
747 .I "job control"
748 commands can take an argument that identifies a particular
749 job.
750 All job name arguments begin with the character `%', since some of the
751 job control commands also accept process numbers (printed by the
752 .I ps
753 command.)
754 The default job (when no argument is given) is called the
755 .I current
756 job and is identified by a `+' in the output of the
757 .I jobs
758 command, which shows you which jobs you have.
759 When only one job is stopped or running in the background (the usual case)
760 it is always the current job thus no argument is needed.
761 If a job is stopped while running in the foreground it becomes the
762 .I current
763 job and the existing current job becomes the
764 .I previous
765 job \- identified by a `\-' in the output of
766 .I jobs.
767 When the current job terminates, the previous job becomes the current job.
768 When given, the argument is either `%\-' (indicating
769 the previous job); `%#', where # is the job number;
770 `%pref' where pref is some unique prefix of the command name
771 and arguments of one of the jobs; or `%?' followed by some string found
772 in only one of the jobs.
775 .I jobs
776 command types the table of jobs, giving the job number,
777 commands and status (`Stopped' or `Running') of each backgound or
778 suspended job.  With the `\-l' option the process numbers are also
779 typed.
781 % du > usage &
782 [1] 3398
783 % ls \-s | sort \-n > myfile &
784 [2] 3405
785 % mail bill
787 Stopped
788 % jobs
789 .ta 1.75i
790 [1] \(mi Running        du > usage
791 [2]    Running  ls \-s | sort \-n > myfile
792 [3] \(pl Stopped        mail bill
793 % fg %ls
794 ls \-s | sort \-n > myfile
795 % more myfile
796 .so tabs
800 .I fg
801 command runs a suspended or background job in the foreground.  It is
802 used to restart a previously suspended job or change a background job
803 to run in the foreground (allowing signals or input from the terminal).
804 In the above example we used
805 .I fg
806 to change the `ls' job from the
807 background to the foreground since we wanted to wait for it to
808 finish before looking at its output file.
810 .I bg
811 command runs a suspended job in the background.  It is usually used
812 after stopping the currently running foreground job with the
813 \s-2STOP\s0 signal.  The combination of the \s-2STOP\s0 signal and the
814 .I bg
815 command changes a foreground job into a background job.
817 .I stop
818 command suspends a background job.
821 .I kill
822 command terminates a background or suspended job immediately.
823 In addition to jobs, it may be given process numbers as arguments,
824 as printed by
825 .I ps.
826 Thus, in the example above, the running
827 .I du
828 command could have been terminated by the command
830 % kill %1
831 .ta 1.75i
832 [1]  Terminated du > usage
834 .so tabs
838 .I notify
839 command (not the variable mentioned earlier) indicates that the termination
840 of a specific job should be
841 reported at the time it finishes instead of waiting for the next prompt.
843 If a job running in the background tries to read input from the terminal
844 it is automatically stopped.  When such a job is then run in the
845 foreground, input can be given to the job.  If desired, the job can
846 be run in the background again until it requests input again.
847 This is illustrated in the following sequence where the `s' command in the
848 text editor might take a long time.
851 % ed bigfile
852 120000
853 1,$s/thisword/thatword/
855 Stopped
856 % bg
857 [1] ed bigfile &
859  . . .  some foreground commands
860 .ta 1.75i
861 [1] Stopped (tty input) ed bigfile
862 % fg
863 ed bigfile
865 120000
868 .so tabs
870 So after the `s' command was issued, the `ed' job was stopped with ^Z
871 and then put in the background using
872 .I bg.
873 Some time later when the `s' command was finished,
874 .I ed
875 tried to read another command and was stopped because jobs
876 in the backgound cannot read from the terminal.  The
877 .I fg
878 command returned the `ed' job to the foreground where it could once again
879 accept commands from the terminal.
881 The command
883 stty tostop
885 causes all background jobs run on your terminal to stop
886 when they are about to
887 write output to the terminal.  This prevents messages from background
888 jobs from interrupting foreground job output and allows you to run
889 a job in the background without losing terminal output.  It also
890 can be used for interactive programs that sometimes have long
891 periods without interaction.  Thus each time it outputs a prompt for more
892 input it will stop before the prompt.  It can then be run in the
893 foreground using
894 .I fg,
895 more input can be given and, if necessary stopped and returned to
896 the background.  This
897 .I stty
898 command might be a good thing to put in your
899 .I \&.login
900 file if you do not like output from background jobs interrupting
901 your work.  It also can reduce the need for redirecting the output
902 of background jobs if the output is not very big:
904 % stty tostop
905 % wc hugefile &
906 [1] 10387
907 % ed text
908 \&. . . some time later
910 .ta 1.75i
911 [1] Stopped (tty output)        wc hugefile
912 % fg wc
913 wc hugefile
914    13371   30123   302577
915 % stty \-tostop
916 .so tabs
918 Thus after some time the `wc' command, which counts the lines, words
919 and characters in a file, had one line of output.  When it tried to
920 write this to the terminal it stopped.  By restarting it in the
921 foreground we allowed it to write on the terminal exactly when we were
922 ready to look at its output.
923 Programs which attempt to change the mode of the terminal will also
924 block, whether or not
925 .I tostop
926 is set, when they are not in the foreground, as
927 it would be very unpleasant to have a background job change the state
928 of the terminal.
930 Since the
931 .I jobs
932 command only prints jobs started in the currently executing shell,
933 it knows nothing about background jobs started in other login sessions
934 or within shell files.  The
935 .I ps
936 can be used in this case to find out about background jobs not started
937 in the current shell.
938 .NH 2
939 Working Directories
941 As mentioned in section 1.6, the shell is always in a particular
942 .I "working directory."
943 The `change directory' command
944 .I chdir
945 (its
946 short form
947 .I cd
948 may also be used)
949 changes the working directory of the shell,
950 that is, changes the directory you
951 are located in.
953 It is useful to make a directory for each project you wish to work on
954 and to place all files related to that project in that directory.
955 The `make directory' command,
956 .I mkdir,
957 creates a new directory.
959 .I pwd
960 (`print working directory') command
961 reports the absolute pathname of the working directory of the shell,
962 that is, the directory you are
963 located in.
964 Thus in the example below:
966 % pwd
967 /usr/bill
968 % mkdir newpaper
969 % chdir newpaper
970 % pwd
971 /usr/bill/newpaper
974 the user has created and moved to the
975 directory
976 .I newpaper.
977 where, for example, he might
978 place a group of related files.
980 No matter where you have moved to in a directory hierarchy,
981 you can return to your `home' login directory by doing just
985 with no arguments.
986 The name `..' always means the directory above the current one in
987 the hierarchy, thus
989 cd ..
991 changes the shell's working directory to the one directly above the
992 current one.
993 The name `..' can be used in any
994 pathname, thus,
996 cd ../programs
998 means
999 change to the directory `programs' contained in the directory
1000 above the current one.
1001 If you have several directories for different
1002 projects under, say, your home directory,
1003 this shorthand notation
1004 permits you to switch easily between them.
1006 The shell always remembers the pathname of its current working directory in
1007 the variable
1008 .I cwd.
1009 The shell can also be requested to remember the previous directory when
1010 you change to a new working directory.  If the `push directory' command
1011 .I pushd
1012 is used in place of the
1013 .I cd
1014 command, the shell saves the name of the current working directory
1015 on a
1016 .I "directory stack"
1017 before changing to the new one.
1018 You can see this list at any time by typing the `directories'
1019 command
1020 .I dirs.
1023 % pushd newpaper/references
1024 ~/newpaper/references  ~
1025 % pushd /usr/lib/tmac
1026 /usr/lib/tmac  ~/newpaper/references  ~
1027 % dirs
1028 /usr/lib/tmac  ~/newpaper/references  ~
1029 % popd
1030 ~/newpaper/references  ~
1031 % popd
1035 The list is printed in a horizontal line, reading left to right,
1036 with a tilde (~) as
1037 shorthand for your home directory\(emin this case `/usr/bill'.
1038 The directory stack is printed whenever there is more than one
1039 entry on it and it changes.
1040 It is also printed by a
1041 .I dirs
1042 command.
1043 .I Dirs
1044 is usually faster and more informative than
1045 .I pwd
1046 since it shows the current working directory as well as any
1047 other directories remembered in the stack.
1050 .I pushd
1051 command with no argument
1052 alternates the current directory with the first directory in the
1053 list.
1054 The `pop directory'
1055 .I popd
1056 command without an argument returns you to the directory you were in prior to
1057 the current one, discarding the previous current directory from the
1058 stack (forgetting it).
1059 Typing
1060 .I popd
1061 several times in a series takes you backward through the directories
1062 you had been in (changed to) by
1063 .I pushd
1064 command.
1065 There are other options to
1066 .I pushd
1068 .I popd
1069 to manipulate the contents of the directory stack and to change
1070 to directories not at the top of the stack; see the
1071 .I csh
1072 manual page for details.
1074 Since the shell remembers the working directory in which each job
1075 was started, it warns you when you might be confused by restarting
1076 a job in the foreground which has a different working directory than the
1077 current working directory of the shell.  Thus if you start a background
1078 job, then change the shell's working directory and then cause the
1079 background job to run in the foreground, the shell warns you that the
1080 working directory of the currently running foreground job is different
1081 from that of the shell.
1083 % dirs \-l
1084 /mnt/bill
1085 % cd myproject
1086 % dirs
1087 ~/myproject
1088 % ed prog.c
1089 1143
1091 Stopped
1092 % cd ..
1093 % ls
1094 myproject
1095 textfile
1096 % fg
1097 ed prog.c (wd: ~/myproject)
1099 This way the shell warns you when there
1100 is an implied change of working directory, even though no cd command was
1101 issued.  In the above example the `ed' job was still in `/mnt/bill/project'
1102 even though the shell had changed to `/mnt/bill'.
1103 A similar warning is given when such a foreground job
1104 terminates or is suspended (using the \s-2STOP\s0 signal) since
1105 the return to the shell again implies a change of working directory.
1107 % fg
1108 ed prog.c (wd: ~/myproject)
1109  . . . after some editing
1111 (wd now: ~)
1114 These messages are sometimes confusing if you use programs that change
1115 their own working directories, since the shell only remembers which
1116 directory a job is started in, and assumes it stays there.
1117 The `\-l' option of
1118 .I jobs
1119 will type the working directory
1120 of suspended or background jobs when it is different
1121 from the current working directory of the shell.
1122 .NH 2
1123 Useful built-in commands
1125 We now give a few of the useful built-in commands of the shell describing
1126 how they are used.
1129 .I alias
1130 command described above is used to assign new aliases and to show the
1131 existing aliases.
1132 With no arguments it prints the current aliases.
1133 It may also be given only one argument such as
1135 alias ls
1137 to show the current alias for, e.g., `ls'.
1140 .I echo
1141 command prints its arguments.
1142 It is often used in
1143 .I "shell scripts"
1144 or as an interactive command
1145 to see what filename expansions will produce.
1148 .I history
1149 command will show the contents of the history list.
1150 The numbers given with the history events can be used to reference
1151 previous events which are difficult to reference using the
1152 contextual mechanisms introduced above.
1153 There is also a shell variable called
1154 .I prompt.
1155 By placing a `!' character in its value the shell will there substitute
1156 the number of the current command in the history list.
1157 You can use this number to refer to this command in a history substitution.
1158 Thus you could
1160 set prompt=\'\e! % \'
1162 Note that the `!' character had to be
1163 .I escaped
1164 here even within `\'' characters.
1167 .I limit
1168 command is used to restrict use of resources.
1169 With no arguments it prints the current limitations:
1171 .ta 1i
1172 cputime unlimited
1173 filesize        unlimited
1174 datasize        5616 kbytes
1175 stacksize       512 kbytes
1176 coredumpsize    unlimited
1177 .so tabs
1179 Limits can be set, e.g.:
1181 limit coredumpsize 128k
1183 Most reasonable units abbreviations will work; see the
1184 .I csh
1185 manual page for more details.
1188 .I logout
1189 command can be used to terminate a login shell which has
1190 .I ignoreeof
1191 set.
1194 .I rehash
1195 command causes the shell to recompute a table of where commands are
1196 located.  This is necessary if you add a command to a directory
1197 in the current shell's search path and wish the shell to find it,
1198 since otherwise the hashing algorithm may tell the shell that the
1199 command wasn't in that directory when the hash table was computed.
1202 .I repeat
1203 command can be used to repeat a command several times.
1204 Thus to make 5 copies of the file
1205 .I one
1206 in the file
1207 .I five
1208 you could do
1210 repeat 5 cat one >> five
1214 .I setenv
1215 command can be used
1216 to set variables in the environment.
1217 Thus
1219 setenv TERM adm3a
1221 will set the value of the environment variable \s-2TERM\s0
1223 `adm3a'.
1224 A user program
1225 .I printenv
1226 exists which will print out the environment.
1227 It might then show:
1229 % printenv
1230 HOME=/usr/bill
1231 SHELL=/bin/csh
1232 PATH=:/usr/ucb:/bin:/usr/bin:/usr/local
1233 TERM=adm3a
1234 USER=bill
1239 .I source
1240 command can be used to force the current shell to read commands from
1241 a file.
1242 Thus
1244 source .cshrc
1246 can be used after editing in a change to the
1247 .I \&.cshrc
1248 file which you wish to take effect right away.
1251 .I time
1252 command can be used to cause a command to be timed no matter how much
1253 \s-2CPU\s0 time it takes.
1254 Thus
1256 % time cp /etc/rc /usr/bill/rc
1257 0.0u 0.1s 0:01 8% 2+1k 3+2io 1pf+0w
1258 % time wc /etc/rc /usr/bill/rc
1259      52    178   1347 /etc/rc
1260      52    178   1347 /usr/bill/rc
1261     104    356   2694 total
1262 0.1u 0.1s 0:00 13% 3+3k 5+3io 7pf+0w
1265 indicates that the
1266 .I cp
1267 command used a negligible amount of user time (u)
1268 and about 1/10th of a system time (s); the elapsed time was 1 second (0:01),
1269 there was an average memory usage of 2k bytes of program space and 1k
1270 bytes of data space over the cpu time involved (2+1k); the program
1271 did three disk reads and two disk writes (3+2io), and took one page fault
1272 and was not swapped (1pf+0w).
1273 The word count command
1274 .I wc
1275 on the other hand used 0.1 seconds of user time and 0.1 seconds of system
1276 time in less than a second of elapsed time.
1277 The percentage `13%' indicates that over the period when it was active
1278 the command `wc' used an average of 13 percent of the available \s-2CPU\s0
1279 cycles of the machine.
1282 .I unalias
1284 .I unset
1285 commands can be used
1286 to remove aliases and variable definitions from the shell, and
1287 .I unsetenv
1288 removes variables from the environment.
1289 .NH 2
1290 What else?
1292 This concludes the basic discussion of the shell for terminal users.
1293 There are more features of the shell to be discussed here, and all
1294 features of the shell are discussed in its manual pages.
1295 One useful feature which is discussed later is the
1296 .I foreach
1297 built-in command which can be used to run the same command
1298 sequence with a number of different arguments.
1300 If you intend to use \s-2UNIX\s0 a lot you you should look through
1301 the rest of this document and the csh manual pages (section1) to become familiar
1302 with the other facilities which are available to you.