/share/doc/usd/04.csh/csh.2

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