debug

windows版本的emacs

Debugging GNU Emacs
Copyright (c) 1985, 2000, 2001 Free Software Foundation, Inc.

   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.

[People who debug Emacs on Windows using native Windows debuggers
should read the Windows-specific section near the end of this
document.]

It is a good idea to run Emacs under GDB (or some other suitable
debugger) *all the time*.  Then, when Emacs crashes, you will be able
to debug the live process, not just a core dump.  (This is especially
important on systems which don't support core files, and instead print
just the registers and some stack addresses.)

If Emacs hangs, or seems to be stuck in some infinite loop, typing
"kill -TSTP PID", where PID is the Emacs process ID, will cause GDB to
kick in, provided that you run under GDB.

** Getting control to the debugger

`Fsignal' is a very useful place to put a breakpoint 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.  When using X, this is easy: type C-z at the
window where Emacs is running under GDB, and it will stop Emacs just
as it would stop any ordinary program.  When Emacs is running in a
terminal, things are not so easy.

The src/.gdbinit file in the Emacs distribution arranges for SIGINT
(C-g in Emacs) to be passed to Emacs and not give control back to GDB.
On modern POSIX systems, you can override that with this command:

   handle SIGINT stop nopass

After this `handle' command, SIGINT will return control to GDB.  If
you want the C-g to cause a QUIT within Emacs as well, omit the
`nopass'.

A technique that can work when `handle SIGINT' does not is to store
the code for some character into the variable stop_character.  Thus,

    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.

** 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.

Note: It is not a good idea to try `pr' if you know that Emacs is in
deep trouble: its stack smashed (e.g., if it encountered SIGSEGV due
to stack overflow), or crucial data structures, such as `obarray',
corrupted, etc.  In such cases, the Emacs subroutine called by `pr'
might make more damage, like overwrite some data that is important for
debugging the original problem.

Also, on some systems it is impossible to use `pr' if you stopped
Emacs while it was inside `select'.  This is in fact what happens if
you stop Emacs while it is waiting.  In such a situation, don't try to
use `pr'.  Instead, use `s' to step out of the system call.  Then
Emacs will be between instructions and capable of handling `pr'.

If you can't use `pr' command, for whatever reason, 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
internally.)

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 additional Lisp
objects which you can examine in turn with the x... commands.

Even with a live process, these x...  commands are useful for
examining the fields in a buffer, window, process, frame or marker.
Here's an example using concepts explained in the node "Value History"
of the GDB manual to print the variable frame from this line in
xmenu.c:

		  buf.frame_or_window = frame;

First, use these commands:

    cd src
    gdb emacs
    b xmenu.c:1296
    r -q 

Then type C-x 5 2 to create a new frame, and it hits the breakpoint:

    (gdb) p frame
    $1 = 1077872640
    (gdb) xtype
    Lisp_Vectorlike
    PVEC_FRAME
    (gdb) xframe
    $2 = (struct frame *) 0x3f0800
    (gdb) p *$
    $3 = {
      size = 536871989, 
      next = 0x366240, 
      name = 809661752, 
      [...]
    }
    (gdb) p $3->name
    $4 = 809661752

Now we can use `pr' to print the name of the frame:

    (gdb) pr
    "[e-mail]"

The Emacs C code heavily uses macros defined in lisp.h.  So suppose
we want the address of the l-value expression near the bottom of
`add_command_key' from keyboard.c:

  XVECTOR (this_command_keys)->contents[this_command_key_count++] = key;

XVECTOR is a macro, and therefore GDB does not know about it.
GDB cannot evaluate "p XVECTOR (this_command_keys)".

However, you can use the xvector command in GDB to get the same
result.  Here is how:

    (gdb) p this_command_keys
    $1 = 1078005760
    (gdb) xvector
    $2 = (struct Lisp_Vector *) 0x411000
    0
    (gdb) p $->contents[this_command_key_count]
    $3 = 1077872640
    (gdb) p &$
    $4 = (int *) 0x411008

Here's a related example of macros and the GDB `define' command.
There are many Lisp vectors such as `recent_keys', which contains the
last 100 keystrokes.  We can print this Lisp vector

p recent_keys
pr

But this may be inconvenient, since `recent_keys' is much more verbose
than `C-h l'.  We might want to print only the last 10 elements of
this vector.  `recent_keys' is updated in keyboard.c by the command

  XVECTOR (recent_keys)->contents[recent_keys_index] = c;

So we define a GDB command `xvector-elts', so the last 10 keystrokes
are printed by 

    xvector-elts recent_keys recent_keys_index 10

where you can define xvector-elts as follows:

    define xvector-elts
    set $i = 0
    p $arg0
    xvector
    set $foo = $
    while $i < $arg2
    p $foo->contents[$arg1-($i++)] 
    pr
    end
    document xvector-elts
    Prints a range of elements of a Lisp vector.
    xvector-elts  v n i
    prints `i' elements of the vector `v' ending at the index `n'.
    end

** Getting Lisp-level backtrace information within GDB

The most convenient way is to use the `xbacktrace' command.  This
shows the names of the Lisp functions that are currently active.

If that doesn't work (e.g., because the `backtrace_list' structure is
corrupted), type "bt" at the GDB prompt, to produce the C-level
backtrace, and look for stack frames that call Ffuncall.  Select them
one by one in GDB, by typing "up N", where N is the appropriate number
of frames to go up, and in each frame that calls Ffuncall type this:

   p *args
   pr

This will print the name of the Lisp function called by that level
of function calling.

By printing the remaining elements of args, you can see the argument
values.  Here's how to print the first argument:
  
   p args[1]
   pr

If you do not have a live process, you can use xtype and the other
x...  commands such as xsymbol to get such information, albeit less
conveniently.  For example:

   p *args
   xtype

and, assuming that "xtype" says that args[0] is a symbol:

   xsymbol 

** Debugging what happens while preloading and dumping Emacs

Type `gdb temacs' and start it with `r -batch -l loadup dump'.

If temacs actually succeeds when running under GDB in this way, do not
try to run the dumped Emacs, because it was dumped with the GDB
breakpoints in it.

** Debugging `temacs'

Debugging `temacs' is useful when you want to establish whether a
problem happens in an undumped Emacs.  To run `temacs' under a
debugger, type "gdb temacs", then start it with `r -batch -l loadup'.

** If you encounter X protocol errors

Try evaluating (x-synchronize t).  That puts Emacs into synchronous
mode, where each Xlib call checks for errors before it returns.  This
mode is much slower, but when you get an error, you will see exactly
which call really caused the error.

You can start Emacs in a synchronous mode by invoking it with the -xrm
option, like this:

    emacs -xrm "emacs.synchronous: true"

Setting a breakpoint in the function `x_error_quitter' and looking at
the backtrace when Emacs stops inside that function will show what
code causes the X protocol errors.

Some bugs related to the X protocol disappear when Emacs runs in a
synchronous mode.  To track down those bugs, we suggest the following
procedure:

  - Run Emacs under a debugger and put a breakpoint inside the
    primitive function which, when called from Lisp, triggers the X
    protocol errors.  For example, if the errors happen when you
    delete a frame, put a breakpoint inside `Fdelete_frame'.

  - When the breakpoint breaks, step through the code, looking for
    calls to X functions (the ones whose names begin with "X" or
    "Xt" or "Xm").

  - Insert calls to `XSync' before and after each call to the X
    functions, like this:

       XSync (f->output_data.x->display_info->display, 0);

    where `f' is the pointer to the `struct frame' of the selected
    frame, normally available via XFRAME (selected_frame).  (Most
    functions which call X already have some variable that holds the
    pointer to the frame, perhaps called `f' or `sf', so you shouldn't
    need to compute it.)

    If your debugger can call functions in the program being debugged,
    you should be able to issue the calls to `XSync' without recompiling
    Emacs.  For example, with GDB, just type:

       call XSync (f->output_data.x->display_info->display, 0)

    before and immediately after the suspect X calls.  If your
    debugger does not support this, you will need to add these pairs
    of calls in the source and rebuild Emacs.

    Either way, systematically step through the code and issue these
    calls until you find the first X function called by Emacs after
    which a call to `XSync' winds up in the function
    `x_error_quitter'.  The first X function call for which this
    happens is the one that generated the X protocol error.

  - You should now look around this offending X call and try to figure
    out what is wrong with it.

** If the symptom of the bug is that Emacs fails to respond

Don't assume Emacs is `hung'--it may instead be in an infinite loop.
To find out which, make the problem happen under GDB and stop Emacs
once it is not responding.  (If Emacs is using X Windows directly, you
can stop Emacs by typing C-z at the GDB job.)  Then try stepping with
`step'.  If Emacs is hung, the `step' command won't return.  If it is
looping, `step' will return.

If this shows Emacs is hung in a system call, stop it again and
examine the arguments of the call.  If you report the bug, it is very
important to state exactly where in the source the system call is, and
what the arguments are.