Newer Older
Dave Love's avatar
Dave Love committed
Debugging GNU Emacs
Gerd Moellmann's avatar
Gerd Moellmann committed
Copyright (c) 1985, 2000 Free Software Foundation, Inc.
Dave Love's avatar
Dave Love committed
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35

   Permission is granted to anyone to make or distribute verbatim copies
   of this document as received, in any medium, provided that the
   copyright notice and permission notice are preserved,
   and that the distributor grants the recipient permission
   for further redistribution as permitted by this notice.

   Permission is granted to distribute modified versions
   of this document, or of portions of it,
   under the above conditions, provided also that they
   carry prominent notices stating who last changed them.

** Some useful techniques

`Fsignal' is a very useful place to stop in.
All Lisp errors go through there.

It is useful, when debugging, to have a guaranteed way
to return to the debugger at any time.  If you are using
interrupt-driven input, which is the default, then Emacs is using
RAW mode and the only way you can do it is to store
the code for some character into the variable stop_character:

    set stop_character = 29

makes Control-] (decimal code 29) the stop character.
Typing Control-] will cause immediate stop.  You cannot
use the set command until the inferior process has been started.
Put a breakpoint early in `main', or suspend the Emacs,
to get an opportunity to do the set command.

If you are using cbreak input (see the Lisp function set-input-mode),
then typing Control-g will cause a SIGINT, which will return control
Gerd Moellmann's avatar
Gerd Moellmann committed
to GDB immediately if you type this command first:
Dave Love's avatar
Dave Love committed

Gerd Moellmann's avatar
Gerd Moellmann committed
    handle 2 stop
Dave Love's avatar
Dave Love committed
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114

** Examining Lisp object values.

When you have a live process to debug, and it has not encountered a
fatal error, you can use the GDB command `pr'.  First print the value
in the ordinary way, with the `p' command.  Then type `pr' with no
arguments.  This calls a subroutine which uses the Lisp printer.

If you can't use this command, either because the process can't run
a subroutine or because the data is invalid, you can fall back on
lower-level commands.

Use the `xtype' command to print out the data type of the last data
value.  Once you know the data type, use the command that corresponds
to that type.  Here are these commands:

    xint xptr xwindow xmarker xoverlay xmiscfree xintfwd xboolfwd xobjfwd
    xbufobjfwd xkbobjfwd xbuflocal xbuffer xsymbol xstring xvector xframe
    xwinconfig xcompiled xcons xcar xcdr xsubr xprocess xfloat xscrollbar

Each one of them applies to a certain type or class of types.
(Some of these types are not visible in Lisp, because they exist only

Each x... command prints some information about the value, and
produces a GDB value (subsequently available in $) through which you
can get at the rest of the contents.

In general, most of the rest of the contents will be addition Lisp
objects which you can examine in turn with the x... commands.

** If GDB does not run and your debuggers can't load Emacs.

On some systems, no debugger can load Emacs with a symbol table,
perhaps because they all have fixed limits on the number of symbols
and Emacs exceeds the limits.  Here is a method that can be used
in such an extremity.  Do

    nm -n temacs > nmout
    strip temacs
    adb temacs
    :r -l loadup   (or whatever)

It is necessary to refer to the file `nmout' to convert
numeric addresses into symbols and vice versa.

It is useful to be running under a window system.
Then, if Emacs becomes hopelessly wedged, you can create
another window to do kill -9 in.  kill -ILL is often
useful too, since that may make Emacs dump core or return
to adb.

** Debugging incorrect screen updating.

To debug Emacs problems that update the screen wrong, it is useful
to have a record of what input you typed and what Emacs sent to the
screen.  To make these records, do

(open-dribble-file "~/.dribble")
(open-termscript "~/.termscript")

The dribble file contains all characters read by Emacs from the
terminal, and the termscript file contains all characters it sent to
the terminal.  The use of the directory `~/' prevents interference
with any other user.

If you have irreproducible display problems, put those two expressions
in your ~/.emacs file.  When the problem happens, exit the Emacs that
you were running, kill it, and rename the two files.  Then you can start
another Emacs without clobbering those files, and use it to examine them.
115 116 117 118 119

An easy way to see if too much text is being redrawn on a terminal is to
evaluate `(setq inverse-video t)' before you try the operation you think
will cause too much redrawing.  This doesn't refresh the screen, so only
newly drawn text is in inverse video.