@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 Free Software
+@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@iftex
@chapter Dealing with Common Problems
finished executing. @xref{Undo}, for more information about the undo
facility.
-@node Lossage, Bugs, Quitting, Top
+@node Lossage
@section Dealing with Emacs Trouble
This section describes how to recognize and deal with situations in
* Screen Garbled:: Garbage on the screen.
* Text Garbled:: Garbage in the text.
* Memory Full:: How to cope when you run out of memory.
+* Crashing:: What Emacs does when it crashes.
* After a Crash:: Recovering editing in an Emacs session that crashed.
* Emergency Escape:: What to do if Emacs stops responding.
@end menu
too suggests Emacs got the wrong information---but in the opposite
sense.
- On a text-only terminal, if you find that @key{Backspace} prompts
-for a Help command, like @kbd{Control-h}, instead of deleting a
-character, it means that key is actually sending the @key{BS}
-character. Emacs ought to be treating @key{BS} as @key{DEL}, but it
-isn't.
+ On a text terminal, if you find that @key{Backspace} prompts for a
+Help command, like @kbd{Control-h}, instead of deleting a character,
+it means that key is actually sending the @key{BS} character. Emacs
+ought to be treating @key{BS} as @key{DEL}, but it isn't.
@findex normal-erase-is-backspace-mode
In all of those cases, the immediate remedy is the same: use the
command @kbd{M-x normal-erase-is-backspace-mode}. This toggles
between the two modes that Emacs supports for handling @key{DEL}, so
if Emacs starts in the wrong mode, this should switch to the right
-mode. On a text-only terminal, if you want to ask for help when
-@key{BS} is treated as @key{DEL}, use @key{F1}; @kbd{C-?} may also
-work, if it sends character code 127.
+mode. On a text terminal, if you want to ask for help when @key{BS}
+is treated as @key{DEL}, use @key{F1}; @kbd{C-?} may also work, if it
+sends character code 127.
To fix the problem in every Emacs session, put one of the following
lines into your initialization file (@pxref{Init File}). For the
editing in the same Emacs session.
Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run
-out of memory, because the buffer menu needs a fair amount of memory
+out of memory, because the Buffer Menu needs a fair amount of memory
itself, and the reserve supply may not be enough.
+@node Crashing
+@subsection When Emacs Crashes
+
+@cindex crash report
+@cindex backtrace
+@cindex @file{emacs_backtrace.txt} file, MS-Windows
+ Emacs is not supposed to crash, but if it does, it produces a
+@dfn{crash report} prior to exiting. The crash report is printed to
+the standard error stream. If Emacs was started from a graphical
+desktop on a GNU or Unix system, the standard error stream is commonly
+redirected to a file such as @file{~/.xsession-errors}, so you can
+look for the crash report there. On MS-Windows, the crash report is
+written to a file named @file{emacs_backtrace.txt} in the current
+directory of the Emacs process, in addition to the standard error
+stream.
+
+ The format of the crash report depends on the platform. On some
+platforms, such as those using the GNU C Library, the crash report
+includes a @dfn{backtrace} describing the execution state prior to
+crashing, which can be used to help debug the crash. Here is an
+example for a GNU system:
+
+@example
+Fatal error 11: Segmentation fault
+Backtrace:
+emacs[0x5094e4]
+emacs[0x4ed3e6]
+emacs[0x4ed504]
+/lib64/libpthread.so.0[0x375220efe0]
+/lib64/libpthread.so.0(read+0xe)[0x375220e08e]
+emacs[0x509af6]
+emacs[0x5acc26]
+@dots{}
+@end example
+
+@noindent
+The number @samp{11} is the system signal number corresponding to the
+crash---in this case a segmentation fault. The hexadecimal numbers
+are program addresses, which can be associated with source code lines
+using a debugging tool. For example, the GDB command
+@samp{list *0x509af6} prints the source-code lines corresponding to
+the @samp{emacs[0x509af6]} entry. If your system has the
+@command{addr2line} utility, the following shell command outputs a
+backtrace with source-code line numbers:
+
+@example
+sed -n 's/.*\[\(.*\)]$/\1/p' @var{backtrace} |
+ addr2line -Cfip -e @var{bindir}/@var{emacs-binary}
+@end example
+
+@noindent
+Here, @var{backtrace} is the name of a text file containing a copy of
+the backtrace, @var{bindir} is the name of the directory that
+contains the Emacs executable, and @var{emacs-binary} is the name of
+the Emacs executable file, normally @file{emacs} on GNU and Unix
+systems and @file{emacs.exe} on MS-Windows and MS-DOS.
+
+@cindex core dump
+ Optionally, Emacs can generate a @dfn{core dump} when it crashes, on
+systems that support core files. A core dump is a file containing
+voluminous data about the state of the program prior to the crash,
+usually examined by loading it into a debugger such as GDB@. On many
+platforms, core dumps are disabled by default, and you must explicitly
+enable them by running the shell command @samp{ulimit -c unlimited}
+(e.g., in your shell startup script).
+
@node After a Crash
@subsection Recovery After a Crash
@file{core.emacs}, so that another crash won't overwrite it.
To use this script, run @code{gdb} with the file name of your Emacs
-executable and the file name of the core dump, e.g. @samp{gdb
+executable and the file name of the core dump, e.g., @samp{gdb
/usr/bin/emacs core.emacs}. At the @code{(gdb)} prompt, load the
recovery script: @samp{source /usr/src/emacs/etc/emacs-buffer.gdb}.
Then type the command @code{ybuffer-list} to see which buffers are
@node Emergency Escape
@subsection Emergency Escape
- On text-only terminals, the @dfn{emergency escape} feature suspends
-Emacs immediately if you type @kbd{C-g} a second time before Emacs can
+ On text terminals, the @dfn{emergency escape} feature suspends Emacs
+immediately if you type @kbd{C-g} a second time before Emacs can
actually respond to the first one by quitting. This is so you can
always get out of GNU Emacs no matter how badly it might be hung.
When things are working properly, Emacs recognizes and handles the
emergency escape---but there are cases where it won't work, when
system call hangs or when Emacs is stuck in a tight loop in C code.
-@node Bugs, Contributing, Lossage, Top
+@node Bugs
@section Reporting Bugs
@cindex bugs
from Emacs using the @code{debbugs} package, which can be downloaded
via the Package Menu (@pxref{Packages}). This package provides the
command @kbd{M-x debbugs-gnu} to list bugs, and @kbd{M-x
-debbugs-gnu-search} to search for a specific bug.
+debbugs-gnu-search} to search for a specific bug. User tags, applied
+by the Emacs maintainers, are shown by @kbd{M-x debbugs-gnu-usertags}.
@item
The @samp{bug-gnu-emacs} mailing list (also available as the newsgroup
would need to provide all that information. You should not assume
that the problem is due to the size of the file and say, ``I visited a
large file, and Emacs displayed @samp{I feel pretty today}.'' This is
-what we mean by ``guessing explanations.'' The problem might be due
+what we mean by ``guessing explanations''. The problem might be due
to the fact that there is a @samp{z} in the file name. If this is so,
then when we got your report, we would try out the problem with some
-``large file,'' probably with no @samp{z} in its name, and not see any
+``large file'', probably with no @samp{z} in its name, and not see any
problem. There is no way we could guess that we should try visiting a
file with a @samp{z} in its name.
You should not even say ``visit a file'' instead of @kbd{C-x C-f}.
Similarly, rather than saying ``if I have three characters on the
-line,'' say ``after I type @kbd{@key{RET} A B C @key{RET} C-p},'' if
+line'', say ``after I type @kbd{@key{RET} A B C @key{RET} C-p}'', if
that is the way you entered the text.
If possible, try quickly to reproduce the bug by invoking Emacs with
will be sent to the Emacs maintainers at @email{bug-gnu-emacs@@gnu.org}.
(If you want to suggest an improvement or new feature, use the same
address.) If you cannot send mail from inside Emacs, you can copy the
-text of your report to your normal mail client and send it to that
-address. Or you can simply send an email to that address describing
-the problem.
+text of your report to your normal mail client (if your system
+supports it, you can type @kbd{C-c m} to have Emacs do this for you)
+and send it to that address. Or you can simply send an email to that
+address describing the problem.
Your report will be sent to the @samp{bug-gnu-emacs} mailing list, and
stored in the GNU Bug Tracker at @url{http://debbugs.gnu.org}. Please
The type of machine you are using, and the operating system name and
version number (again, automatically included by @kbd{M-x
report-emacs-bug}). @kbd{M-x emacs-version @key{RET}} provides this
-information too. Copy its output from the @samp{*Messages*} buffer,
+information too. Copy its output from the @file{*Messages*} buffer,
so that you get it all and get it accurately.
@item
@end example
@noindent
-using @kbd{M-:} or from the @samp{*scratch*} buffer just after
+using @kbd{M-:} or from the @file{*scratch*} buffer just after
starting Emacs. From then on, Emacs copies all terminal output to the
specified termscript file as well, until the Emacs process is killed.
If the problem happens when Emacs starts up, put this expression into
to display your locale settings.
You can use the @kbd{M-!} command to execute these commands from
-Emacs, and then copy the output from the @samp{*Messages*} buffer into
+Emacs, and then copy the output from the @file{*Messages*} buffer into
the bug report. Alternatively, @kbd{M-x getenv @key{RET} LC_ALL
@key{RET}} will display the value of @code{LC_ALL} in the echo area, and
-you can copy its output from the @samp{*Messages*} buffer.
+you can copy its output from the @file{*Messages*} buffer.
@item
A description of what behavior you observe that you believe is
-incorrect. For example, ``The Emacs process gets a fatal signal,'' or,
+incorrect. For example, ``The Emacs process gets a fatal signal'', or,
``The resulting text is as follows, which I think is wrong.''
Of course, if the bug is that Emacs gets a fatal signal, then one can't
backtrace showing how the Lisp program in Emacs arrived at the error.
To get the error message text accurately, copy it from the
-@samp{*Messages*} buffer into the bug report. Copy all of it, not just
+@file{*Messages*} buffer into the bug report. Copy all of it, not just
part.
@findex toggle-debug-on-error
This backtrace is useful for debugging such long loops, so if you can
produce it, copy it into the bug report.
+@vindex debug-on-event
+If you cannot get Emacs to respond to @kbd{C-g} (e.g., because
+@code{inhibit-quit} is set), then you can try sending the signal
+specified by @code{debug-on-event} (default SIGUSR2) from outside
+Emacs to cause it to enter the debugger.
+
@item
Check whether any programs you have loaded into the Lisp world,
including your initialization file, set any variables that may affect
are available in the file @file{etc/DEBUG} in the Emacs distribution.
That file also includes instructions for investigating problems
whereby Emacs stops responding (many people assume that Emacs is
-``hung,'' whereas in fact it might be in an infinite loop).
+``hung'', whereas in fact it might be in an infinite loop).
To find the file @file{etc/DEBUG} in your Emacs installation, use the
directory name stored in the variable @code{data-directory}.
form that is clearly safe to install.
@end itemize
-@node Contributing, Service, Bugs, Top
+@node Contributing
@section Contributing to Emacs Development
@cindex contributing to Emacs
For more information on how to contribute, see the @file{etc/CONTRIBUTE}
file in the Emacs distribution.
-@node Service, Copying, Contributing, Top
+@node Service
@section How To Get Help with GNU Emacs
If you need help installing, using or changing GNU Emacs, there are two