.TH NEWCSH 1
.UC
.bd S 3
.SH NAME
newcsh \- description of new csh features (over oldcsh)
.SH SYNOPSIS
.B csh
\fIcsh-options\fP
.SH SUMMARY
This is a summary of features new in
.IR csh (1)
in this version of the system; an older version of
.I csh
is available as
.I oldcsh.
This newer
.I csh
has some new process control primitives and a few other new features.
Users of
.I csh
must (and automatically) use the new terminal driver (summarized in
.IR newtty(4)
and completely described with the old in
.IR tty (4))
which allows generation of some new
interrupt signals from the keyboard which tell jobs to stop,
and arbitrates access to the terminal;
on CRT's the command ``stty crt'' is
normally placed in the
.I .login
file to be executed at login,
to set other useful modes of this terminal driver.
.PP
.B "Jobs."
.PP
The most important new feature in this shell is the control of
.I jobs.
A job is associated with each pipeline, where a pipeline is either
a simple command like ``date'', or a pipeline like ``who | wc''.
The shell keeps a table of current jobs, and assigns them small
integer numbers.
When you start a job in the background, the shell prints a line
which looks like:
.PP
\ \ \ \ [1] 1234
.PP
this indicating that the job which was started asynchronously with ``&''
is job number 1 and has one (top-level) process, whose process id is 1234.
The set of current jobs is listed by the
.I jobs
command.
.PP
If you are running a job and wish to do something else you may hit the
key ^Z (control-Z) which sends a
.I stop
signal to the current job.  The shell will then normally indicate that
the job has been ``Stopped'', and print another prompt.
You can then
put the job in the background with the command ``bg'', or run
some other commands and then return the job to the foreground with
``fg''.
A ^Z takes effect immediately and is like an interrupt in that
pending output and unread input are discarded when it is typed.
There is another special key ^Y which does not generate a stop signal
until a program attempts to
.IR read (2)
it.
This can usefully be typed ahead when you have prepared some commands
for a job which you wish to stop after it has read them.
.PP
A job being run in the background will stop if it tries to read
from the terminal.  Background jobs are normally allowed to produce output,
but this can be disabled by doing ``stty tostop''.  If you set this
tty option, then background jobs will stop when they try to produce
output like they do when they try to read input.
.PP
There are several ways to refer to jobs in the shell.  The character
``%'' introduces a job name.  If you wish to refer to job number 1, you can
name it as ``%1''.  Just naming a job brings it to the foreground; thus
``%1'' is a synonym for ``fg %1'', bringing job 1 back into the foreground.
Similarly saying ``%1 &'' resumes job 1 in the background.
Jobs can also be named by prefixes of the string typed in to start them,
if these prefixes are unambiguous, thus ``%ex'' would normally restart
a suspended
.IR ex (1)
job, if there were only one suspended job whose name began with
the string ``ex''.  It is also possible to say ``%?string''
which specifies a job whose text contains
.I string,
if there is only one such job.
.PP
The shell also maintains a notion of the current and previous jobs.
In output pertaining to jobs, the current job is marked with a ``+''
and the previous job with a ``\-''.  The abbreviation ``%+'' refers
to the current job and ``%\-'' refers to the previous job.  For close
analogy with the
.I history
mechanism,
``%%'' is also a synonym for the current job.
.PP
.B "Status reporting."
.PP
This shell learns immediately whenever a process changes state.
It normally informs you whenever a job becomes blocked so that
no further progress is possible, but only just before it prints
a prompt.  This is done so that it does not otherwise disturb your work.
If, however, you set the shell variable
.I notify,
the shell will notify you immediately of changes of status in background
jobs.
There is also a shell command
.I notify
which marks a single process so that its status changes will be immediately
reported.  By default 
.I notify
marks the current process;
simply say ``notify'' after starting a background job to mark it.
.PP
When you try to leave the shell while jobs are stopped, you will
be warned that ``You have stopped jobs.''  You may use the ``jobs''
command to see what they are.  If you do this or immediately try to
exit again, the shell will not warn you a second time, and the suspended
jobs will be unmercifully terminated.
.PP
.B "New builtin commands."
.HP 5
.B bg
.br
.ns
.HP 5
\fBbg\ %\fPjob\ ...
.br
Puts the current or specified jobs into the background, continuing them
if they were stopped.
.HP 5
.B fg
.br
.ns
.HP 5
\fBfg\ %\fPjob\ ...
.br
Brings the current or specified jobs into the foreground, continuing them if
they were stopped.
.HP 5
.B jobs
.br
.ns
.HP 5
.B "jobs \-l"
.br
Lists the active jobs; given the
.B \-l
options lists process id's in addition to the normal information.
.HP 5
\fBkill %\fPjob
.br
.ns
.HP 5
\fBkill\ \-\fPsig\ \fB%\fPjob\ ...
.br
.ns
.HP 5
\fBkill\fP\ pid
.br
.ns
.HP 5
\fBkill\ \-\fPsig\ pid\ ...
.br
.ns
.HP 5
\fBkill\ \-l\fP
.br
Sends either the TERM (terminate) signal or the
specified signal to the specified jobs or processes.
Signals are either given by number or by names (as given in
.I /usr/include/signal.h,
stripped of the prefix ``SIG'').
The signal names are listed by ``kill \-l''.
There is no default, saying just `kill' does not
send a signal to the current job.
If the signal being sent is TERM (terminate) or HUP (hangup),
then the job or process will be sent a CONT (continue) signal as well.
.HP 5
.B notify
.br
.ns
.HP 5
\fBnotify\ %\fPjob\ ...
.br
Causes the shell to notify the user asynchronously when the status of the
current or specified jobs changes; normally notification is presented
before a prompt.  All jobs are marked ``notify'' if the shell variable
``notify'' is set.
.HP 5
\fBstop\ %\fPjob\ ...
.br
Stops the specified job which is executing in the background.
.HP 5
\fB%\fPjob
.br
Brings the specified job into the foreground.
.HP 5
\fB%\fPjob \fB&\fP
.br
Continues the specified job in the background.
.br
.ne 5
.PP
.B "Process limitations."
.PP
The shell provides access (on VAX-11 systems)
to an experimental facility for limiting
the consumption by a single process of system resources.
The following commands control this facility:
.HP 5
\fBlimit\fP \fIresource\fP \fImaximum-use\fP
.HP 5
\fBlimit\fP \fIresource\fP
.br
.ns
.HP
\fBlimit\fP
.br
Limits the consumption by the current process and each process
it creates to not individually exceed \fImaximum-use\fP on the
specified \fIresource\fP.  If no \fImaximum-use\fP is given, then
the current limit is printed; if no \fIresource\fP is given, then
all limitations are given.
.IP
Resources controllable currently include \fIcputime\fP (the maximum
number of cpu-seconds to be used by each process), \fIfilesize\fP
(the largest single file which can be created), \fIdatasize\fP
(the maximum growth of the data+stack region via
.IR sbrk (2)
beyond the end of the program text), \fIstacksize\fP (the maximum
size of the automatically-extended stack region), and \fIcoredumpsize\fP
(the size of the largest core dump that will be created).
.IP
The \fImaximum-use\fP may be given as a (floating point or integer)
number followed by a scale factor.  For all limits other than \fIcputime\fP
the default scale is ``k'' or ``kilobytes'' (1024 bytes);
a scale factor of ``m'' or ``megabytes'' may also be used.
For cputime the default scaling is ``seconds'', while ``m'' for minutes
or ``h'' for hours, or a time of the form ``mm:ss'' giving minutes
and seconds may be used.
.IP
For both \fIresource\fP names and scale factors, unambiguous prefixes
of the names suffice.
.HP 5
\fBunlimit\fP \fIresource\fP
.br
.ns
.HP 5
\fBunlimit\fP
.br
Removes the limitation on \fIresource\fP.  If no \fIresource\fP
is specified, then all \fIresource\fP limitations are removed.
.ne 5
.PP
.B "Directory stack."
.PP
This shell now keeps track of the current directory (which is kept
in the variable
.I cwd)
and also maintains a stack of directories, which is printed by the
command
.I dirs.
You can change to a new directory and push down the old directory
stack by using the command
.I pushd
which is otherwise like the 
.I chdir
command, changing to its argument.
You can pop the directory stack by saying
.I popd.
Saying
.I pushd
with no arguments exchanges the top two elements of the directory stack.
The elements of the directory stack are numbered from 1 starting at the top.
Saying
.I pushd
with a argument ``+\fIn\fP'' rotates the directory stack to make that entry
in the stack be at the top and changes to it.
Giving
.I popd
a ``+\fIn\fP'' argument eliminates that argument from the directory stack.
.PP
.B "Miscellaneous."
.PP
This shell imports the environment variable USER into the variable
.I user,
TERM into
.I term,
and
HOME into
.I home,
and exports these back into the environment whenever the normal
shell variables are reset.
The environment variable PATH is likewise handled; it is not
necessary to worry about its setting other than in the file
.I \&.cshrc
as inferior
.I csh
processes will import the definition of
.I path
from the environment, and re-export it if you then change it.
(It could be set once in the
.I \&.login
except that commands over the Berknet would not
see the definition.)
.PP
There are new commands
.I eval,
which is like the eval of the Bourne shell
.IR sh (1),
and useful with
.IR tset (1),
and
.I suspend
which stops a shell (as though a ^Z had stopped it; since
shells normally ignore ^Z signals, this command is necessary.)
.PP
There is a new variable
.I cdpath;
if set, then each directory in
.I cdpath
will be searched for a directory named in a
.I chdir
command if there is no such subdirectory of the current directory.
.PP
An
.I unsetenv
command removing environment variables has been added.
.PP
There is a new ``:'' modifier ``:e'', which yields the extension
portion of a filename.  Thus if ``$a'' is ``file.c'', ``$a:e'' is ``c''.
.PP
There are two new operators in shell expressions ``!~'' and ``=~'' which
are like the string operations ``!='' and ``=='' except that the right
hand side is a
.I pattern
(containing, e.g. ``*''s, ``?''s and instances of ``[...]'')
against which the left hand operand is matched.  This reduces the
need for use of the
.I switch
statement in shell scripts when all that is really needed is pattern matching.
.PP
The form ``$<'' is new, and is replaced by a line from the standard
input, with no further interpretation thereafter.  It may therefore
be used to read from the keyboard in a shell script.
.SH "SEE ALSO"
csh(1), killpg(2), signal(2), sigsys(2), jobs(3), sigset(3), tty(4)
.SH BUGS
Command sequences of the form ``a ; b ; c'' are not handled gracefully
when stopping is attempted.  If you suspend ``b'', the shell will then
immediately execute ``c''.  This is especially noticeable if this
expansion results from an
.I alias.
It suffices to place the sequence of commands in ()'s to force it to
a subshell, i.e. ``( a ; b ; c )'', but see the next bug.
.PP
Shell builtin functions are not stoppable/restartable.
.PP
Control over output is primitive;
perhaps this will inspire someone to work on a good virtual
terminal interface.  In a virtual terminal interface much more
interesting things could be done with output control.