address@hidden: Proposal of Emacs shell mode "panic situation" document]

[Richard Stallman]

It might be useful to improve the English of this
and put it into the etc directory.  We don't have papers
from him yet, but I asked him if he is willing to sign.

------- Start of forwarded message -------
Date: Sat, 10 Nov 2001 05:13:21 +0900
From: Prophet of the Way <address@hidden>
X-Accept-Language: ja
To: address@hidden
Subject: Proposal of Emacs shell mode "panic situation" document

This document tells you how to handle "panic situations".  This is for running
the shell with M-x shell under Emacs.


1.  Tell me how to reboot.

Quick and dirty reboot: C-M-delete (Ctrl, Meta, Delete keys pushed down
together.  Meta is Alt on some keyboards.)

If you reboot while running Emacs, editing performed on files not yet saved will
be lost.  Try to close down Emacs orderly with C-x C-c.

Rebooting is the last resort.  Only a disaster gives you an excuse for
unplugging a running machine.


2.  Everything on the screen disappeared and a login prompt appeared.

PC Linux systems support a feature called 'virtual consoles'.  You can switch
consoles by typing Meta with a function key: M-F2 for example.  Pushing Meta and
an arrow key together achieves the same effect.  Sometimes we do this without
knowing so and it looks like suddenly getting lost.

To get back to the first console, type M-F1.


3.  The man command produces funny output and keeps asking for "RETURN".

Emacs shell mode cannot handle output from man:

$ man grep
WARNING: terminal is not fully functional

- -  (press RETURN)

Instead use M-x man.  Also try info with C-h i.

Utilities called "pagers", the commands 'more' and 'less', which allow you to
scroll through text files do not work within shell mode.  We don't need them
within Emacs where the scroll capabilities are already provided.  If a Unix
instruction book tells you to do something like:

$ stty -all | more

simply ignore the '| more' or '| less'.

You can also redirect the output:

$ stty -all > /tmp/sam.txt

and visit the temporary file /tmp/sam.txt with C-x C-r.


4.  The prompt changed to '> '.  Hitting return just gives more prompts.

'> ' is called the 'secondary prompt'.  This appears when we type in commands
which are more than one line long.  For example:

$ for i in modem.txt protocol.txt transmission.txt
> do
> sed 's/64K/64k/g' $i > $i.new
> done

Sometimes we mistype our intentions.  In the following example, the shell,
expecting more, gives us a fresh line for the sequel:

$ grep '[1-9][0-9]*[Kk] ~/doc/modem.txt
>

You can get out of this by canceling the command with C-c C-c.


5.  I get the reply "command not found" whatever I input.

Example:

$ cal
bash: cal: command not found
$ 

It's likely you've corrupted the PATH enviroment value.  Without PATH, your
machine won't be able to tell the directories where binary executables are
placed.

Check this by executing set and looking for PATH.  Try executing this from the
command line as well as by M-! set.

$ set
...
PATH=.:/usr/local/bin:/usr/bin:/bin
...

Another method is using the echo command:

bash:

$ /bin/echo $PATH
.:/usr/local/bin:/usr/bin:/bin

csh, tcsh:

% /bin/echo $path
. /usr/local/bin /bin /usr/bin

Above are the ordinary replies.  If you get a blank response or garbish, the
variable is corrupted.  Note that you must provide absolute paths for commands
in this case.

You can get the location, within the file structure, of commands with 'which':

$ which echo
/bin/echo

Usually things get back to normal when you login again.  If they don't, you've
probably corrupted or erased your login script.  This is a shell script that is
executed every time you login (or start a new shell).

There is only one way out of this is to and it's to be prepared.

Backup your .bash* or .csh* files.  Keep a written memo of your PATH value to
handle this situation.  Take a look at the contents of the directories listed in
PATH.  Draw a diagaram of the file structure.

You may encounter the same trouble when the hard disk has suffered serious
damage.  In this case absolute paths do not work.  You usually have to reinstall
the OS in this case.


6.  How can I abort a command taking much longer to process than expected?

To stop a command in execution, type C-c C-c.  If C-c C-c does not work, type
C-c C-\.

C-c C-c tries to end things orderly.  C-c C-\ is stronger but may have side
effects.

More often we suspend a command in execution with C-c C-z.  This temporary halts
execution of the command.  The 'bg' command resumes execution of the suspended
command in the background.  This will free your terminal and allow you to do
other things.  The 'fg' command resumes execution in the foreground.

Whenever it seems you've stepped into an unknown command by mistake, C-c C-z is
the first thing you should try.


7.  How can I abort execution of jobs running in the background?

One way, of course, is to bring it into the foreground and give it a C-c C-c.

Usually, we use the 'kill' command.  This command takes a parameter, the process
ID (PID) of the command you want to kill.  To find out the process ID, execute
the ps command.  In the next example we abort 'find': 

$ ps
  PID TTY STAT TIME COMMAND
  146   1 S    0:00 -bash 
  159   1 S    0:00 emacs20 
  160  p0 S    0:00 /bin/bash -i 
  574  p0 S    0:01 find / -name *.txt -exec sed -n s/foo/FOO/p {} ; 
  738  p0 R    0:00 sed -n s/foo/FOO/p /usr/doc/misc/riddles.txt
  739  p0 R    0:00 ps 

$ kill 574

The R in the STAT column stands for running.  T stands for terminated.

Execute 'ps' once again after the 'kill' to check.

If 'kill' doesn't work, try the almighty version: 'kill -KILL'.

You can use 'kill' against suspended jobs as well as running jobs.  Be careful
because you are allowed to kill emacs or bash.  If, for some reason, you want to
kill the shell, kill the *shell* buffer using C-x k.

You can even kill processes running under different terminals.  Sometimes this
is the only way to stop a runaway process and put things back to control.  You
can login from another terminal if you're accessing via a network environment.
Or you can switch virtual consoles with M-Fn.  Note the TTY column of the ps
report when doing this.


8.  More information on shell mode.

Visit the info page for 'shell mode' in the Emacs manual.  With Emacs running
you can get near there with C-h C-f shell.


9.  These instructions don't work at all.

Most probably you're reading the wrong troubleshooting manual.

What operating system are you using?  The above instructions are for PC based
GNU/Linux systems running Emacs.  Excluding three-key-reboot and switching
between virtual consoles, the procedures apply for Unix systems in general. 
They do not work at all for Mac OS, MS-DOS or MS Windows, etc.

Note that I write nothing about mouse-clicks, menus and icons.  The above is
written for character based terminals.  There may be some differences if you are
using a terminal emulator within a graphical window system (xterm in X Window).

There are also some differences if you run the shell outside instead of within
Emacs.  The first C-c gets scraped off from abort/suspend commands outside
Emacs: C-c C-z becomes C-z, etc.  Note that C-s means 'freeze screen' outside
Emacs.  Your terminal will stop displaying all new output.  To get out, press
C-q.


10.  A note for the beginner.

You may be reading this online.  You will not be able to come back here in case
of emergency.  Write the procedures down in your notebook.  Don't set this off
for a later date.

Some of the subjects discussed above are somewhat advanced.  Don't worry if you
don't understand fully.  You'll learn in time.  More important is the fact that
you'll learn how to investigate.  We learn through trial and error.  I wrote
this for you hoping that it will help you recover from the errors.

11.  Acknowledgement

Thanks to Aya Sakamoto, author of _Tanoshii UNIX_.



Best Regards,

Akira
------- End of forwarded message -------