nt/config.nt: Sync with autogen/config.in.
[emacs.git] / etc / DEBUG
blob20bdd6cdbdc4b99da85b5faf35d4707188651df4
1 Debugging GNU Emacs
3 Copyright (C) 1985, 2000-2012  Free Software Foundation, Inc.
4 See the end of the file for license conditions.
7 [People who debug Emacs on Windows using Microsoft debuggers should
8 read the Windows-specific section near the end of this document.]
10 ** When you debug Emacs with GDB, you should start it in the directory
11 where the executable was made.  That directory has a .gdbinit file
12 that defines various "user-defined" commands for debugging Emacs.
13 (These commands are described below under "Examining Lisp object
14 values" and "Debugging Emacs Redisplay problems".)
16 ** When you are trying to analyze failed assertions, it will be
17 essential to compile Emacs either completely without optimizations or
18 at least (when using GCC) with the -fno-crossjumping option.  Failure
19 to do so may make the compiler recycle the same abort call for all
20 assertions in a given function, rendering the stack backtrace useless
21 for identifying the specific failed assertion.
23 ** It is a good idea to run Emacs under GDB (or some other suitable
24 debugger) *all the time*.  Then, when Emacs crashes, you will be able
25 to debug the live process, not just a core dump.  (This is especially
26 important on systems which don't support core files, and instead print
27 just the registers and some stack addresses.)
29 ** If Emacs hangs, or seems to be stuck in some infinite loop, typing
30 "kill -TSTP PID", where PID is the Emacs process ID, will cause GDB to
31 kick in, provided that you run under GDB.
33 ** Getting control to the debugger
35 `Fsignal' is a very useful place to put a breakpoint in.
36 All Lisp errors go through there.
38 It is useful, when debugging, to have a guaranteed way to return to
39 the debugger at any time.  When using X, this is easy: type C-z at the
40 window where Emacs is running under GDB, and it will stop Emacs just
41 as it would stop any ordinary program.  When Emacs is running in a
42 terminal, things are not so easy.
44 The src/.gdbinit file in the Emacs distribution arranges for SIGINT
45 (C-g in Emacs) to be passed to Emacs and not give control back to GDB.
46 On modern POSIX systems, you can override that with this command:
48    handle SIGINT stop nopass
50 After this `handle' command, SIGINT will return control to GDB.  If
51 you want the C-g to cause a QUIT within Emacs as well, omit the `nopass'.
53 A technique that can work when `handle SIGINT' does not is to store
54 the code for some character into the variable stop_character.  Thus,
56     set stop_character = 29
58 makes Control-] (decimal code 29) the stop character.
59 Typing Control-] will cause immediate stop.  You cannot
60 use the set command until the inferior process has been started.
61 Put a breakpoint early in `main', or suspend the Emacs,
62 to get an opportunity to do the set command.
64 When Emacs is running in a terminal, it is sometimes useful to use a separate
65 terminal for the debug session.  This can be done by starting Emacs as usual,
66 then attaching to it from gdb with the `attach' command which is explained in
67 the node "Attach" of the GDB manual.
69 ** Examining Lisp object values.
71 When you have a live process to debug, and it has not encountered a
72 fatal error, you can use the GDB command `pr'.  First print the value
73 in the ordinary way, with the `p' command.  Then type `pr' with no
74 arguments.  This calls a subroutine which uses the Lisp printer.
76 You can also use `pp value' to print the emacs value directly.
78 To see the current value of a Lisp Variable, use `pv variable'.
80 Note: It is not a good idea to try `pr', `pp', or `pv' if you know that Emacs
81 is in deep trouble: its stack smashed (e.g., if it encountered SIGSEGV
82 due to stack overflow), or crucial data structures, such as `obarray',
83 corrupted, etc.  In such cases, the Emacs subroutine called by `pr'
84 might make more damage, like overwrite some data that is important for
85 debugging the original problem.
87 Also, on some systems it is impossible to use `pr' if you stopped
88 Emacs while it was inside `select'.  This is in fact what happens if
89 you stop Emacs while it is waiting.  In such a situation, don't try to
90 use `pr'.  Instead, use `s' to step out of the system call.  Then
91 Emacs will be between instructions and capable of handling `pr'.
93 If you can't use `pr' command, for whatever reason, you can use the
94 `xpr' command to print out the data type and value of the last data
95 value, For example:
97     p it->object
98     xpr
100 You may also analyze data values using lower-level commands.  Use the
101 `xtype' command to print out the data type of the last data value.
102 Once you know the data type, use the command that corresponds to that
103 type.  Here are these commands:
105     xint xptr xwindow xmarker xoverlay xmiscfree xintfwd xboolfwd xobjfwd
106     xbufobjfwd xkbobjfwd xbuflocal xbuffer xsymbol xstring xvector xframe
107     xwinconfig xcompiled xcons xcar xcdr xsubr xprocess xfloat xscrollbar
109 Each one of them applies to a certain type or class of types.
110 (Some of these types are not visible in Lisp, because they exist only
111 internally.)
113 Each x... command prints some information about the value, and
114 produces a GDB value (subsequently available in $) through which you
115 can get at the rest of the contents.
117 In general, most of the rest of the contents will be additional Lisp
118 objects which you can examine in turn with the x... commands.
120 Even with a live process, these x...  commands are useful for
121 examining the fields in a buffer, window, process, frame or marker.
122 Here's an example using concepts explained in the node "Value History"
123 of the GDB manual to print values associated with the variable
124 called frame.  First, use these commands:
126     cd src
127     gdb emacs
128     b set_frame_buffer_list
129     r -q
131 Then Emacs hits the breakpoint:
133     (gdb) p frame
134     $1 = 139854428
135     (gdb) xpr
136     Lisp_Vectorlike
137     PVEC_FRAME
138     $2 = (struct frame *) 0x8560258
139     "emacs@localhost"
140     (gdb) p *$
141     $3 = {
142       size = 1073742931,
143       next = 0x85dfe58,
144       name = 140615219,
145       [...]
146     }
148 Now we can use `pr' to print the frame parameters:
150     (gdb) pp $->param_alist
151     ((background-mode . light) (display-type . color) [...])
154 The Emacs C code heavily uses macros defined in lisp.h.  So suppose
155 we want the address of the l-value expression near the bottom of
156 `add_command_key' from keyboard.c:
158   XVECTOR (this_command_keys)->contents[this_command_key_count++] = key;
160 XVECTOR is a macro, so GDB only knows about it if Emacs has been compiled with
161 preprocessor macro information.  GCC provides this if you specify the options
162 `-gdwarf-2' and `-g3'.  In this case, GDB can evaluate expressions like
163 "p XVECTOR (this_command_keys)".
165 When this information isn't available, you can use the xvector command in GDB
166 to get the same result.  Here is how:
168     (gdb) p this_command_keys
169     $1 = 1078005760
170     (gdb) xvector
171     $2 = (struct Lisp_Vector *) 0x411000
172     0
173     (gdb) p $->contents[this_command_key_count]
174     $3 = 1077872640
175     (gdb) p &$
176     $4 = (int *) 0x411008
178 Here's a related example of macros and the GDB `define' command.
179 There are many Lisp vectors such as `recent_keys', which contains the
180 last 300 keystrokes.  We can print this Lisp vector
182 p recent_keys
185 But this may be inconvenient, since `recent_keys' is much more verbose
186 than `C-h l'.  We might want to print only the last 10 elements of
187 this vector.  `recent_keys' is updated in keyboard.c by the command
189   XVECTOR (recent_keys)->contents[recent_keys_index] = c;
191 So we define a GDB command `xvector-elts', so the last 10 keystrokes
192 are printed by
194     xvector-elts recent_keys recent_keys_index 10
196 where you can define xvector-elts as follows:
198     define xvector-elts
199     set $i = 0
200     p $arg0
201     xvector
202     set $foo = $
203     while $i < $arg2
204     p $foo->contents[$arg1-($i++)]
205     pr
206     end
207     document xvector-elts
208     Prints a range of elements of a Lisp vector.
209     xvector-elts  v n i
210     prints `i' elements of the vector `v' ending at the index `n'.
211     end
213 ** Getting Lisp-level backtrace information within GDB
215 The most convenient way is to use the `xbacktrace' command.  This
216 shows the names of the Lisp functions that are currently active.
218 If that doesn't work (e.g., because the `backtrace_list' structure is
219 corrupted), type "bt" at the GDB prompt, to produce the C-level
220 backtrace, and look for stack frames that call Ffuncall.  Select them
221 one by one in GDB, by typing "up N", where N is the appropriate number
222 of frames to go up, and in each frame that calls Ffuncall type this:
224    p *args
225    pr
227 This will print the name of the Lisp function called by that level
228 of function calling.
230 By printing the remaining elements of args, you can see the argument
231 values.  Here's how to print the first argument:
233    p args[1]
234    pr
236 If you do not have a live process, you can use xtype and the other
237 x...  commands such as xsymbol to get such information, albeit less
238 conveniently.  For example:
240    p *args
241    xtype
243 and, assuming that "xtype" says that args[0] is a symbol:
245    xsymbol
247 ** Debugging Emacs Redisplay problems
249 The src/.gdbinit file defines many useful commands for dumping redisplay
250 related data structures in a terse and user-friendly format:
252  `ppt' prints value of PT, narrowing, and gap in current buffer.
253  `pit' dumps the current display iterator `it'.
254  `pwin' dumps the current window 'win'.
255  `prow' dumps the current glyph_row `row'.
256  `pg' dumps the current glyph `glyph'.
257  `pgi' dumps the next glyph.
258  `pgrow' dumps all glyphs in current glyph_row `row'.
259  `pcursor' dumps current output_cursor.
261 The above commands also exist in a version with an `x' suffix which
262 takes an object of the relevant type as argument.
264 ** Following longjmp call.
266 Recent versions of glibc (2.4+?) encrypt stored values for setjmp/longjmp which
267 prevents GDB from being able to follow a longjmp call using `next'.  To
268 disable this protection you need to set the environment variable
269 LD_POINTER_GUARD to 0.
271 ** Using GDB in Emacs
273 Debugging with GDB in Emacs offers some advantages over the command line (See
274 the GDB Graphical Interface node of the Emacs manual).  There are also some
275 features available just for debugging Emacs:
277 1) The command gud-pp is available on the tool bar (the `pp' icon) and
278    allows the user to print the s-expression of the variable at point,
279    in the GUD buffer.
281 2) Pressing `p' on a component of a watch expression that is a lisp object
282    in the speedbar prints its s-expression in the GUD buffer.
284 3) The STOP button on the tool bar is adjusted so that it sends SIGTSTP
285    instead of the usual SIGINT.
287 4) The command gud-pv has the global binding 'C-x C-a C-v' and prints the
288    value of the lisp variable at point.
290 ** Debugging what happens while preloading and dumping Emacs
292 Type `gdb temacs' and start it with `r -batch -l loadup dump'.
294 If temacs actually succeeds when running under GDB in this way, do not
295 try to run the dumped Emacs, because it was dumped with the GDB
296 breakpoints in it.
298 ** Debugging `temacs'
300 Debugging `temacs' is useful when you want to establish whether a
301 problem happens in an undumped Emacs.  To run `temacs' under a
302 debugger, type "gdb temacs", then start it with `r -batch -l loadup'.
304 ** If you encounter X protocol errors
306 The X server normally reports protocol errors asynchronously,
307 so you find out about them long after the primitive which caused
308 the error has returned.
310 To get clear information about the cause of an error, try evaluating
311 (x-synchronize t).  That puts Emacs into synchronous mode, where each
312 Xlib call checks for errors before it returns.  This mode is much
313 slower, but when you get an error, you will see exactly which call
314 really caused the error.
316 You can start Emacs in a synchronous mode by invoking it with the -xrm
317 option, like this:
319     emacs -xrm "emacs.synchronous: true"
321 Setting a breakpoint in the function `x_error_quitter' and looking at
322 the backtrace when Emacs stops inside that function will show what
323 code causes the X protocol errors.
325 Some bugs related to the X protocol disappear when Emacs runs in a
326 synchronous mode.  To track down those bugs, we suggest the following
327 procedure:
329   - Run Emacs under a debugger and put a breakpoint inside the
330     primitive function which, when called from Lisp, triggers the X
331     protocol errors.  For example, if the errors happen when you
332     delete a frame, put a breakpoint inside `Fdelete_frame'.
334   - When the breakpoint breaks, step through the code, looking for
335     calls to X functions (the ones whose names begin with "X" or
336     "Xt" or "Xm").
338   - Insert calls to `XSync' before and after each call to the X
339     functions, like this:
341        XSync (f->output_data.x->display_info->display, 0);
343     where `f' is the pointer to the `struct frame' of the selected
344     frame, normally available via XFRAME (selected_frame).  (Most
345     functions which call X already have some variable that holds the
346     pointer to the frame, perhaps called `f' or `sf', so you shouldn't
347     need to compute it.)
349     If your debugger can call functions in the program being debugged,
350     you should be able to issue the calls to `XSync' without recompiling
351     Emacs.  For example, with GDB, just type:
353        call XSync (f->output_data.x->display_info->display, 0)
355     before and immediately after the suspect X calls.  If your
356     debugger does not support this, you will need to add these pairs
357     of calls in the source and rebuild Emacs.
359     Either way, systematically step through the code and issue these
360     calls until you find the first X function called by Emacs after
361     which a call to `XSync' winds up in the function
362     `x_error_quitter'.  The first X function call for which this
363     happens is the one that generated the X protocol error.
365   - You should now look around this offending X call and try to figure
366     out what is wrong with it.
368 ** If Emacs causes errors or memory leaks in your X server
370 You can trace the traffic between Emacs and your X server with a tool
371 like xmon, available at ftp://ftp.x.org/contrib/devel_tools/.
373 Xmon can be used to see exactly what Emacs sends when X protocol errors
374 happen.  If Emacs causes the X server memory usage to increase you can
375 use xmon to see what items Emacs creates in the server (windows,
376 graphical contexts, pixmaps) and what items Emacs delete.  If there
377 are consistently more creations than deletions, the type of item
378 and the activity you do when the items get created can give a hint where
379 to start debugging.
381 ** If the symptom of the bug is that Emacs fails to respond
383 Don't assume Emacs is `hung'--it may instead be in an infinite loop.
384 To find out which, make the problem happen under GDB and stop Emacs
385 once it is not responding.  (If Emacs is using X Windows directly, you
386 can stop Emacs by typing C-z at the GDB job.)  Then try stepping with
387 `step'.  If Emacs is hung, the `step' command won't return.  If it is
388 looping, `step' will return.
390 If this shows Emacs is hung in a system call, stop it again and
391 examine the arguments of the call.  If you report the bug, it is very
392 important to state exactly where in the source the system call is, and
393 what the arguments are.
395 If Emacs is in an infinite loop, try to determine where the loop
396 starts and ends.  The easiest way to do this is to use the GDB command
397 `finish'.  Each time you use it, Emacs resumes execution until it
398 exits one stack frame.  Keep typing `finish' until it doesn't
399 return--that means the infinite loop is in the stack frame which you
400 just tried to finish.
402 Stop Emacs again, and use `finish' repeatedly again until you get back
403 to that frame.  Then use `next' to step through that frame.  By
404 stepping, you will see where the loop starts and ends.  Also, examine
405 the data being used in the loop and try to determine why the loop does
406 not exit when it should.
408 You can also trying sending Emacs SIGUSR2, which, if `debug-on-event'
409 has its default value, will cause Emacs to attempt to break it out of
410 its current loop and into the Lisp debugger.  This feature is useful
411 when a C-level debugger is not conveniently available.
413 ** If certain operations in Emacs are slower than they used to be, here
414 is some advice for how to find out why.
416 Stop Emacs repeatedly during the slow operation, and make a backtrace
417 each time.  Compare the backtraces looking for a pattern--a specific
418 function that shows up more often than you'd expect.
420 If you don't see a pattern in the C backtraces, get some Lisp
421 backtrace information by typing "xbacktrace" or by looking at Ffuncall
422 frames (see above), and again look for a pattern.
424 When using X, you can stop Emacs at any time by typing C-z at GDB.
425 When not using X, you can do this with C-g.  On non-Unix platforms,
426 such as MS-DOS, you might need to press C-BREAK instead.
428 ** If GDB does not run and your debuggers can't load Emacs.
430 On some systems, no debugger can load Emacs with a symbol table,
431 perhaps because they all have fixed limits on the number of symbols
432 and Emacs exceeds the limits.  Here is a method that can be used
433 in such an extremity.  Do
435     nm -n temacs > nmout
436     strip temacs
437     adb temacs
438     0xd:i
439     0xe:i
440     14:i
441     17:i
442     :r -l loadup   (or whatever)
444 It is necessary to refer to the file `nmout' to convert
445 numeric addresses into symbols and vice versa.
447 It is useful to be running under a window system.
448 Then, if Emacs becomes hopelessly wedged, you can create another
449 window to do kill -9 in.  kill -ILL is often useful too, since that
450 may make Emacs dump core or return to adb.
453 ** Debugging incorrect screen updating.
455 To debug Emacs problems that update the screen wrong, it is useful
456 to have a record of what input you typed and what Emacs sent to the
457 screen.  To make these records, do
459 (open-dribble-file "~/.dribble")
460 (open-termscript "~/.termscript")
462 The dribble file contains all characters read by Emacs from the
463 terminal, and the termscript file contains all characters it sent to
464 the terminal.  The use of the directory `~/' prevents interference
465 with any other user.
467 If you have irreproducible display problems, put those two expressions
468 in your ~/.emacs file.  When the problem happens, exit the Emacs that
469 you were running, kill it, and rename the two files.  Then you can start
470 another Emacs without clobbering those files, and use it to examine them.
472 An easy way to see if too much text is being redrawn on a terminal is to
473 evaluate `(setq inverse-video t)' before you try the operation you think
474 will cause too much redrawing.  This doesn't refresh the screen, so only
475 newly drawn text is in inverse video.
477 The Emacs display code includes special debugging code, but it is
478 normally disabled.  You can enable it by building Emacs with the
479 pre-processing symbol GLYPH_DEBUG defined.  Here's one easy way,
480 suitable for Unix and GNU systems, to build such a debugging version:
482          MYCPPFLAGS='-DGLYPH_DEBUG=1' make
484 Building Emacs like that activates many assertions which scrutinize
485 display code operation more than Emacs does normally.  (To see the
486 code which tests these assertions, look for calls to the `xassert'
487 macros.)  Any assertion that is reported to fail should be investigated.
489 Building with GLYPH_DEBUG defined also defines several helper
490 functions which can help debugging display code.  One such function is
491 `dump_glyph_matrix'.  If you run Emacs under GDB, you can print the
492 contents of any glyph matrix by just calling that function with the
493 matrix as its argument.  For example, the following command will print
494 the contents of the current matrix of the window whose pointer is in `w':
496   (gdb) p dump_glyph_matrix (w->current_matrix, 2)
498 (The second argument 2 tells dump_glyph_matrix to print the glyphs in
499 a long form.)  You can dump the selected window's current glyph matrix
500 interactively with "M-x dump-glyph-matrix RET"; see the documentation
501 of this function for more details.
503 Several more functions for debugging display code are available in
504 Emacs compiled with GLYPH_DEBUG defined; type "C-h f dump- TAB" and
505 "C-h f trace- TAB" to see the full list.
507 When you debug display problems running emacs under X, you can use
508 the `ff' command to flush all pending display updates to the screen.
511 ** Debugging LessTif
513 If you encounter bugs whereby Emacs built with LessTif grabs all mouse
514 and keyboard events, or LessTif menus behave weirdly, it might be
515 helpful to set the `DEBUGSOURCES' and `DEBUG_FILE' environment
516 variables, so that one can see what LessTif was doing at this point.
517 For instance
519   export DEBUGSOURCES="RowColumn.c:MenuShell.c:MenuUtil.c"
520   export DEBUG_FILE=/usr/tmp/LESSTIF_TRACE
521   emacs &
523 causes LessTif to print traces from the three named source files to a
524 file in `/usr/tmp' (that file can get pretty large).  The above should
525 be typed at the shell prompt before invoking Emacs, as shown by the
526 last line above.
528 Running GDB from another terminal could also help with such problems.
529 You can arrange for GDB to run on one machine, with the Emacs display
530 appearing on another.  Then, when the bug happens, you can go back to
531 the machine where you started GDB and use the debugger from there.
534 ** Debugging problems which happen in GC
536 The array `last_marked' (defined on alloc.c) can be used to display up
537 to 500 last objects marked by the garbage collection process.
538 Whenever the garbage collector marks a Lisp object, it records the
539 pointer to that object in the `last_marked' array, which is maintained
540 as a circular buffer.  The variable `last_marked_index' holds the
541 index into the `last_marked' array one place beyond where the pointer
542 to the very last marked object is stored.
544 The single most important goal in debugging GC problems is to find the
545 Lisp data structure that got corrupted.  This is not easy since GC
546 changes the tag bits and relocates strings which make it hard to look
547 at Lisp objects with commands such as `pr'.  It is sometimes necessary
548 to convert Lisp_Object variables into pointers to C struct's manually.
550 Use the `last_marked' array and the source to reconstruct the sequence
551 that objects were marked.  In general, you need to correlate the
552 values recorded in the `last_marked' array with the corresponding
553 stack frames in the backtrace, beginning with the innermost frame.
554 Some subroutines of `mark_object' are invoked recursively, others loop
555 over portions of the data structure and mark them as they go.  By
556 looking at the code of those routines and comparing the frames in the
557 backtrace with the values in `last_marked', you will be able to find
558 connections between the values in `last_marked'.  E.g., when GC finds
559 a cons cell, it recursively marks its car and its cdr.  Similar things
560 happen with properties of symbols, elements of vectors, etc.  Use
561 these connections to reconstruct the data structure that was being
562 marked, paying special attention to the strings and names of symbols
563 that you encounter: these strings and symbol names can be used to grep
564 the sources to find out what high-level symbols and global variables
565 are involved in the crash.
567 Once you discover the corrupted Lisp object or data structure, grep
568 the sources for its uses and try to figure out what could cause the
569 corruption.  If looking at the sources doesn't help, you could try
570 setting a watchpoint on the corrupted data, and see what code modifies
571 it in some invalid way.  (Obviously, this technique is only useful for
572 data that is modified only very rarely.)
574 It is also useful to look at the corrupted object or data structure in
575 a fresh Emacs session and compare its contents with a session that you
576 are debugging.
578 ** Debugging problems with non-ASCII characters
580 If you experience problems which seem to be related to non-ASCII
581 characters, such as \201 characters appearing in the buffer or in your
582 files, set the variable byte-debug-flag to t.  This causes Emacs to do
583 some extra checks, such as look for broken relations between byte and
584 character positions in buffers and strings; the resulting diagnostics
585 might pinpoint the cause of the problem.
587 ** Debugging the TTY (non-windowed) version
589 The most convenient method of debugging the character-terminal display
590 is to do that on a window system such as X.  Begin by starting an
591 xterm window, then type these commands inside that window:
593   $ tty
594   $ echo $TERM
596 Let's say these commands print "/dev/ttyp4" and "xterm", respectively.
598 Now start Emacs (the normal, windowed-display session, i.e. without
599 the `-nw' option), and invoke "M-x gdb RET emacs RET" from there.  Now
600 type these commands at GDB's prompt:
602   (gdb) set args -nw -t /dev/ttyp4
603   (gdb) set environment TERM xterm
604   (gdb) run
606 The debugged Emacs should now start in no-window mode with its display
607 directed to the xterm window you opened above.
609 Similar arrangement is possible on a character terminal by using the
610 `screen' package.
612 ** Running Emacs built with malloc debugging packages
614 If Emacs exhibits bugs that seem to be related to use of memory
615 allocated off the heap, it might be useful to link Emacs with a
616 special debugging library, such as Electric Fence (a.k.a. efence) or
617 GNU Checker, which helps find such problems.
619 Emacs compiled with such packages might not run without some hacking,
620 because Emacs replaces the system's memory allocation functions with
621 its own versions, and because the dumping process might be
622 incompatible with the way these packages use to track allocated
623 memory.  Here are some of the changes you might find necessary:
625   - Edit configure, to set system_malloc and CANNOT_DUMP to "yes".
627   - Configure with a different --prefix= option.  If you use GCC,
628     version 2.7.2 is preferred, as some malloc debugging packages
629     work a lot better with it than with 2.95 or later versions.
631   - Type "make" then "make -k install".
633   - If required, invoke the package-specific command to prepare
634     src/temacs for execution.
636   - cd ..; src/temacs
638 (Note that this runs `temacs' instead of the usual `emacs' executable.
639 This avoids problems with dumping Emacs mentioned above.)
641 Some malloc debugging libraries might print lots of false alarms for
642 bitfields used by Emacs in some data structures.  If you want to get
643 rid of the false alarms, you will have to hack the definitions of
644 these data structures on the respective headers to remove the `:N'
645 bitfield definitions (which will cause each such field to use a full
646 int).
648 ** How to recover buffer contents from an Emacs core dump file
650 The file etc/emacs-buffer.gdb defines a set of GDB commands for
651 recovering the contents of Emacs buffers from a core dump file.  You
652 might also find those commands useful for displaying the list of
653 buffers in human-readable format from within the debugger.
655 ** Some suggestions for debugging on MS Windows:
657    (written by Marc Fleischeuers, Geoff Voelker and Andrew Innes)
659 To debug Emacs with Microsoft Visual C++, you either start emacs from
660 the debugger or attach the debugger to a running emacs process.
662 To start emacs from the debugger, you can use the file bin/debug.bat.
663 The Microsoft Developer studio will start and under Project, Settings,
664 Debug, General you can set the command-line arguments and Emacs's
665 startup directory.  Set breakpoints (Edit, Breakpoints) at Fsignal and
666 other functions that you want to examine.  Run the program (Build,
667 Start debug).  Emacs will start and the debugger will take control as
668 soon as a breakpoint is hit.
670 You can also attach the debugger to an already running Emacs process.
671 To do this, start up the Microsoft Developer studio and select Build,
672 Start debug, Attach to process.  Choose the Emacs process from the
673 list.  Send a break to the running process (Debug, Break) and you will
674 find that execution is halted somewhere in user32.dll.  Open the stack
675 trace window and go up the stack to w32_msg_pump.  Now you can set
676 breakpoints in Emacs (Edit, Breakpoints).  Continue the running Emacs
677 process (Debug, Step out) and control will return to Emacs, until a
678 breakpoint is hit.
680 To examine the contents of a Lisp variable, you can use the function
681 'debug_print'.  Right-click on a variable, select QuickWatch (it has
682 an eyeglass symbol on its button in the toolbar), and in the text
683 field at the top of the window, place 'debug_print(' and ')' around
684 the expression.  Press 'Recalculate' and the output is sent to stderr,
685 and to the debugger via the OutputDebugString routine.  The output
686 sent to stderr should be displayed in the console window that was
687 opened when the emacs.exe executable was started.  The output sent to
688 the debugger should be displayed in the 'Debug' pane in the Output
689 window.  If Emacs was started from the debugger, a console window was
690 opened at Emacs' startup; this console window also shows the output of
691 'debug_print'.
693 For example, start and run Emacs in the debugger until it is waiting
694 for user input.  Then click on the `Break' button in the debugger to
695 halt execution.  Emacs should halt in `ZwUserGetMessage' waiting for
696 an input event.  Use the `Call Stack' window to select the procedure
697 `w32_msp_pump' up the call stack (see below for why you have to do
698 this).  Open the QuickWatch window and enter
699 "debug_print(Vexec_path)".  Evaluating this expression will then print
700 out the contents of the Lisp variable `exec-path'.
702 If QuickWatch reports that the symbol is unknown, then check the call
703 stack in the `Call Stack' window.  If the selected frame in the call
704 stack is not an Emacs procedure, then the debugger won't recognize
705 Emacs symbols.  Instead, select a frame that is inside an Emacs
706 procedure and try using `debug_print' again.
708 If QuickWatch invokes debug_print but nothing happens, then check the
709 thread that is selected in the debugger.  If the selected thread is
710 not the last thread to run (the "current" thread), then it cannot be
711 used to execute debug_print.  Use the Debug menu to select the current
712 thread and try using debug_print again.  Note that the debugger halts
713 execution (e.g., due to a breakpoint) in the context of the current
714 thread, so this should only be a problem if you've explicitly switched
715 threads.
717 It is also possible to keep appropriately masked and typecast Lisp
718 symbols in the Watch window, this is more convenient when steeping
719 though the code.  For instance, on entering apply_lambda, you can
720 watch (struct Lisp_Symbol *) (0xfffffff & args[0]).
722 Optimizations often confuse the MS debugger.  For example, the
723 debugger will sometimes report wrong line numbers, e.g., when it
724 prints the backtrace for a crash.  It is usually best to look at the
725 disassembly to determine exactly what code is being run--the
726 disassembly will probably show several source lines followed by a
727 block of assembler for those lines.  The actual point where Emacs
728 crashes will be one of those source lines, but not necessarily the one
729 that the debugger reports.
731 Another problematic area with the MS debugger is with variables that
732 are stored in registers: it will sometimes display wrong values for
733 those variables.  Usually you will not be able to see any value for a
734 register variable, but if it is only being stored in a register
735 temporarily, you will see an old value for it.  Again, you need to
736 look at the disassembly to determine which registers are being used,
737 and look at those registers directly, to see the actual current values
738 of these variables.
741 This file is part of GNU Emacs.
743 GNU Emacs is free software: you can redistribute it and/or modify
744 it under the terms of the GNU General Public License as published by
745 the Free Software Foundation, either version 3 of the License, or
746 (at your option) any later version.
748 GNU Emacs is distributed in the hope that it will be useful,
749 but WITHOUT ANY WARRANTY; without even the implied warranty of
750 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
751 GNU General Public License for more details.
753 You should have received a copy of the GNU General Public License
754 along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
757 Local variables:
758 mode: outline
759 paragraph-separate: "[  \f]*$"
760 end: