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