international/mule.el (set-keyboard-coding-system): Recover input meta mode when...
[bpt/emacs.git] / etc / DEBUG
CommitLineData
a933dad1 1Debugging GNU Emacs
5b87ad55 2
acaf905b 3Copyright (C) 1985, 2000-2012 Free Software Foundation, Inc.
5b87ad55 4See the end of the file for license conditions.
a933dad1 5
a933dad1 6
6259c2ec
GM
7[People who debug Emacs on Windows using Microsoft debuggers should
8read the Windows-specific section near the end of this document.]
437368fe 9
42a3c627 10** When you debug Emacs with GDB, you should start it in the directory
7483daa1
RS
11where the executable was made. That directory has a .gdbinit file
12that defines various "user-defined" commands for debugging Emacs.
a313dc7b
EZ
13(These commands are described below under "Examining Lisp object
14values" and "Debugging Emacs Redisplay problems".)
42a3c627 15
70d9a9cd
DK
16** When you are trying to analyze failed assertions, it will be
17essential to compile Emacs either completely without optimizations or
18at least (when using GCC) with the -fno-crossjumping option. Failure
19to do so may make the compiler recycle the same abort call for all
20assertions in a given function, rendering the stack backtrace useless
21for identifying the specific failed assertion.
22
42a3c627 23** It is a good idea to run Emacs under GDB (or some other suitable
437368fe
EZ
24debugger) *all the time*. Then, when Emacs crashes, you will be able
25to debug the live process, not just a core dump. (This is especially
26important on systems which don't support core files, and instead print
27just the registers and some stack addresses.)
28
42a3c627 29** If Emacs hangs, or seems to be stuck in some infinite loop, typing
437368fe
EZ
30"kill -TSTP PID", where PID is the Emacs process ID, will cause GDB to
31kick in, provided that you run under GDB.
32
33** Getting control to the debugger
a933dad1 34
3102e429 35`Fsignal' is a very useful place to put a breakpoint in.
a933dad1
DL
36All Lisp errors go through there.
37
3102e429 38It is useful, when debugging, to have a guaranteed way to return to
eb55f651 39the debugger at any time. When using X, this is easy: type C-z at the
3102e429
EZ
40window where Emacs is running under GDB, and it will stop Emacs just
41as it would stop any ordinary program. When Emacs is running in a
42terminal, things are not so easy.
43
44The 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.
46On modern POSIX systems, you can override that with this command:
47
7718638c 48 handle SIGINT stop nopass
3102e429
EZ
49
50After this `handle' command, SIGINT will return control to GDB. If
6259c2ec 51you want the C-g to cause a QUIT within Emacs as well, omit the `nopass'.
3102e429
EZ
52
53A technique that can work when `handle SIGINT' does not is to store
54the code for some character into the variable stop_character. Thus,
a933dad1
DL
55
56 set stop_character = 29
57
58makes Control-] (decimal code 29) the stop character.
59Typing Control-] will cause immediate stop. You cannot
60use the set command until the inferior process has been started.
61Put a breakpoint early in `main', or suspend the Emacs,
62to get an opportunity to do the set command.
63
06b6baf6
NR
64When Emacs is running in a terminal, it is sometimes useful to use a separate
65terminal for the debug session. This can be done by starting Emacs as usual,
66then attaching to it from gdb with the `attach' command which is explained in
67the node "Attach" of the GDB manual.
8ef597fe 68
a933dad1
DL
69** Examining Lisp object values.
70
71When you have a live process to debug, and it has not encountered a
72fatal error, you can use the GDB command `pr'. First print the value
73in the ordinary way, with the `p' command. Then type `pr' with no
74arguments. This calls a subroutine which uses the Lisp printer.
75
1ce9f40a
KS
76You can also use `pp value' to print the emacs value directly.
77
11eced2f
KS
78To see the current value of a Lisp Variable, use `pv variable'.
79
80Note: It is not a good idea to try `pr', `pp', or `pv' if you know that Emacs
1ce9f40a
KS
81is in deep trouble: its stack smashed (e.g., if it encountered SIGSEGV
82due to stack overflow), or crucial data structures, such as `obarray',
437368fe
EZ
83corrupted, etc. In such cases, the Emacs subroutine called by `pr'
84might make more damage, like overwrite some data that is important for
85debugging the original problem.
86
3102e429
EZ
87Also, on some systems it is impossible to use `pr' if you stopped
88Emacs while it was inside `select'. This is in fact what happens if
89you stop Emacs while it is waiting. In such a situation, don't try to
90use `pr'. Instead, use `s' to step out of the system call. Then
91Emacs will be between instructions and capable of handling `pr'.
a933dad1 92
11eced2f
KS
93If 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
95value, For example:
96
97 p it->object
98 xpr
99
100You 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.
102Once you know the data type, use the command that corresponds to that
103type. Here are these commands:
a933dad1
DL
104
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
108
109Each 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
111internally.)
112
113Each x... command prints some information about the value, and
114produces a GDB value (subsequently available in $) through which you
115can get at the rest of the contents.
116
437368fe 117In general, most of the rest of the contents will be additional Lisp
a933dad1
DL
118objects which you can examine in turn with the x... commands.
119
437368fe
EZ
120Even with a live process, these x... commands are useful for
121examining the fields in a buffer, window, process, frame or marker.
122Here's an example using concepts explained in the node "Value History"
aa1f38cd
NR
123of the GDB manual to print values associated with the variable
124called frame. First, use these commands:
437368fe
EZ
125
126 cd src
127 gdb emacs
aa1f38cd 128 b set_frame_buffer_list
177c0ea7 129 r -q
437368fe 130
8ef597fe 131Then Emacs hits the breakpoint:
437368fe
EZ
132
133 (gdb) p frame
aa1f38cd 134 $1 = 139854428
11eced2f 135 (gdb) xpr
437368fe
EZ
136 Lisp_Vectorlike
137 PVEC_FRAME
aa1f38cd 138 $2 = (struct frame *) 0x8560258
11eced2f 139 "emacs@localhost"
437368fe
EZ
140 (gdb) p *$
141 $3 = {
aa1f38cd
NR
142 size = 1073742931,
143 next = 0x85dfe58,
144 name = 140615219,
437368fe
EZ
145 [...]
146 }
437368fe 147
11eced2f
KS
148Now we can use `pr' to print the frame parameters:
149
150 (gdb) pp $->param_alist
151 ((background-mode . light) (display-type . color) [...])
437368fe 152
437368fe
EZ
153
154The Emacs C code heavily uses macros defined in lisp.h. So suppose
155we want the address of the l-value expression near the bottom of
156`add_command_key' from keyboard.c:
157
158 XVECTOR (this_command_keys)->contents[this_command_key_count++] = key;
159
f6e405a2
NR
160XVECTOR is a macro, so GDB only knows about it if Emacs has been compiled with
161preprocessor 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)".
437368fe 164
f6e405a2
NR
165When this information isn't available, you can use the xvector command in GDB
166to get the same result. Here is how:
437368fe
EZ
167
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
177
178Here's a related example of macros and the GDB `define' command.
179There are many Lisp vectors such as `recent_keys', which contains the
6d02b70b 180last 300 keystrokes. We can print this Lisp vector
437368fe
EZ
181
182p recent_keys
183pr
184
185But this may be inconvenient, since `recent_keys' is much more verbose
186than `C-h l'. We might want to print only the last 10 elements of
187this vector. `recent_keys' is updated in keyboard.c by the command
188
189 XVECTOR (recent_keys)->contents[recent_keys_index] = c;
190
191So we define a GDB command `xvector-elts', so the last 10 keystrokes
177c0ea7 192are printed by
437368fe
EZ
193
194 xvector-elts recent_keys recent_keys_index 10
195
196where you can define xvector-elts as follows:
197
198 define xvector-elts
199 set $i = 0
200 p $arg0
201 xvector
202 set $foo = $
203 while $i < $arg2
177c0ea7 204 p $foo->contents[$arg1-($i++)]
437368fe
EZ
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
212
213** Getting Lisp-level backtrace information within GDB
214
3102e429
EZ
215The most convenient way is to use the `xbacktrace' command. This
216shows the names of the Lisp functions that are currently active.
437368fe
EZ
217
218If that doesn't work (e.g., because the `backtrace_list' structure is
219corrupted), type "bt" at the GDB prompt, to produce the C-level
220backtrace, and look for stack frames that call Ffuncall. Select them
221one by one in GDB, by typing "up N", where N is the appropriate number
222of frames to go up, and in each frame that calls Ffuncall type this:
223
224 p *args
225 pr
226
227This will print the name of the Lisp function called by that level
228of function calling.
229
230By printing the remaining elements of args, you can see the argument
231values. Here's how to print the first argument:
177c0ea7 232
437368fe
EZ
233 p args[1]
234 pr
235
236If you do not have a live process, you can use xtype and the other
237x... commands such as xsymbol to get such information, albeit less
238conveniently. For example:
239
240 p *args
241 xtype
242
243and, assuming that "xtype" says that args[0] is a symbol:
244
177c0ea7 245 xsymbol
437368fe 246
11eced2f
KS
247** Debugging Emacs Redisplay problems
248
249The src/.gdbinit file defines many useful commands for dumping redisplay
250related data structures in a terse and user-friendly format:
251
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.
260
261The above commands also exist in a version with an `x' suffix which
262takes an object of the relevant type as argument.
263
6205d23a
NR
264** Following longjmp call.
265
266Recent versions of glibc (2.4+?) encrypt stored values for setjmp/longjmp which
267prevents GDB from being able to follow a longjmp call using `next'. To
268disable this protection you need to set the environment variable
269LD_POINTER_GUARD to 0.
270
c167547b
NR
271** Using GDB in Emacs
272
273Debugging with GDB in Emacs offers some advantages over the command line (See
274the GDB Graphical Interface node of the Emacs manual). There are also some
275features available just for debugging Emacs:
276
a313dc7b
EZ
2771) 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.
c167547b
NR
280
2812) 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.
283
2843) The STOP button on the tool bar is adjusted so that it sends SIGTSTP
285 instead of the usual SIGINT.
286
2874) 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.
289
437368fe
EZ
290** Debugging what happens while preloading and dumping Emacs
291
292Type `gdb temacs' and start it with `r -batch -l loadup dump'.
293
294If temacs actually succeeds when running under GDB in this way, do not
295try to run the dumped Emacs, because it was dumped with the GDB
296breakpoints in it.
297
298** Debugging `temacs'
299
300Debugging `temacs' is useful when you want to establish whether a
301problem happens in an undumped Emacs. To run `temacs' under a
302debugger, type "gdb temacs", then start it with `r -batch -l loadup'.
303
304** If you encounter X protocol errors
305
a2ebb43f
RS
306The X server normally reports protocol errors asynchronously,
307so you find out about them long after the primitive which caused
308the error has returned.
309
310To get clear information about the cause of an error, try evaluating
311(x-synchronize t). That puts Emacs into synchronous mode, where each
312Xlib call checks for errors before it returns. This mode is much
313slower, but when you get an error, you will see exactly which call
314really caused the error.
437368fe 315
ec4054f0
EZ
316You can start Emacs in a synchronous mode by invoking it with the -xrm
317option, like this:
318
9031cdf2 319 emacs -xrm "emacs.synchronous: true"
ec4054f0
EZ
320
321Setting a breakpoint in the function `x_error_quitter' and looking at
322the backtrace when Emacs stops inside that function will show what
323code causes the X protocol errors.
324
1d3adc26
EZ
325Some bugs related to the X protocol disappear when Emacs runs in a
326synchronous mode. To track down those bugs, we suggest the following
327procedure:
328
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'.
333
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").
337
338 - Insert calls to `XSync' before and after each call to the X
339 functions, like this:
340
341 XSync (f->output_data.x->display_info->display, 0);
342
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.)
348
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:
352
353 call XSync (f->output_data.x->display_info->display, 0)
354
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.
358
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.
364
365 - You should now look around this offending X call and try to figure
366 out what is wrong with it.
367
46def989
JD
368** If Emacs causes errors or memory leaks in your X server
369
370You can trace the traffic between Emacs and your X server with a tool
371like xmon, available at ftp://ftp.x.org/contrib/devel_tools/.
372
373Xmon can be used to see exactly what Emacs sends when X protocol errors
374happen. If Emacs causes the X server memory usage to increase you can
375use xmon to see what items Emacs creates in the server (windows,
376graphical contexts, pixmaps) and what items Emacs delete. If there
377are consistently more creations than deletions, the type of item
378and the activity you do when the items get created can give a hint where
379to start debugging.
380
437368fe
EZ
381** If the symptom of the bug is that Emacs fails to respond
382
383Don't assume Emacs is `hung'--it may instead be in an infinite loop.
384To find out which, make the problem happen under GDB and stop Emacs
385once it is not responding. (If Emacs is using X Windows directly, you
386can 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
388looping, `step' will return.
389
390If this shows Emacs is hung in a system call, stop it again and
391examine the arguments of the call. If you report the bug, it is very
392important to state exactly where in the source the system call is, and
393what the arguments are.
394
395If Emacs is in an infinite loop, try to determine where the loop
396starts 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
398exits one stack frame. Keep typing `finish' until it doesn't
399return--that means the infinite loop is in the stack frame which you
400just tried to finish.
401
402Stop Emacs again, and use `finish' repeatedly again until you get back
403to that frame. Then use `next' to step through that frame. By
404stepping, you will see where the loop starts and ends. Also, examine
405the data being used in the loop and try to determine why the loop does
406not exit when it should.
407
0438ce91
DC
408You can also trying sending Emacs SIGUSR2, which, if `debug-on-event'
409has its default value, will cause Emacs to attempt to break it out of
410its current loop and into the Lisp debugger. This feature is useful
411when a C-level debugger is not conveniently available.
412
437368fe
EZ
413** If certain operations in Emacs are slower than they used to be, here
414is some advice for how to find out why.
415
416Stop Emacs repeatedly during the slow operation, and make a backtrace
417each time. Compare the backtraces looking for a pattern--a specific
418function that shows up more often than you'd expect.
419
420If you don't see a pattern in the C backtraces, get some Lisp
421backtrace information by typing "xbacktrace" or by looking at Ffuncall
422frames (see above), and again look for a pattern.
423
424When using X, you can stop Emacs at any time by typing C-z at GDB.
425When not using X, you can do this with C-g. On non-Unix platforms,
426such as MS-DOS, you might need to press C-BREAK instead.
427
a933dad1
DL
428** If GDB does not run and your debuggers can't load Emacs.
429
430On some systems, no debugger can load Emacs with a symbol table,
431perhaps because they all have fixed limits on the number of symbols
432and Emacs exceeds the limits. Here is a method that can be used
433in such an extremity. Do
434
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)
443
444It is necessary to refer to the file `nmout' to convert
445numeric addresses into symbols and vice versa.
446
447It is useful to be running under a window system.
6259c2ec
GM
448Then, if Emacs becomes hopelessly wedged, you can create another
449window to do kill -9 in. kill -ILL is often useful too, since that
450may make Emacs dump core or return to adb.
a933dad1
DL
451
452
453** Debugging incorrect screen updating.
454
455To debug Emacs problems that update the screen wrong, it is useful
456to have a record of what input you typed and what Emacs sent to the
457screen. To make these records, do
458
459(open-dribble-file "~/.dribble")
460(open-termscript "~/.termscript")
461
462The dribble file contains all characters read by Emacs from the
463terminal, and the termscript file contains all characters it sent to
464the terminal. The use of the directory `~/' prevents interference
465with any other user.
466
467If you have irreproducible display problems, put those two expressions
468in your ~/.emacs file. When the problem happens, exit the Emacs that
469you were running, kill it, and rename the two files. Then you can start
470another Emacs without clobbering those files, and use it to examine them.
125f929e
MB
471
472An easy way to see if too much text is being redrawn on a terminal is to
473evaluate `(setq inverse-video t)' before you try the operation you think
474will cause too much redrawing. This doesn't refresh the screen, so only
475newly drawn text is in inverse video.
437368fe 476
3f715e77
EZ
477The Emacs display code includes special debugging code, but it is
478normally disabled. You can enable it by building Emacs with the
479pre-processing symbol GLYPH_DEBUG defined. Here's one easy way,
480suitable for Unix and GNU systems, to build such a debugging version:
481
482 MYCPPFLAGS='-DGLYPH_DEBUG=1' make
483
484Building Emacs like that activates many assertions which scrutinize
485display code operation more than Emacs does normally. (To see the
486code which tests these assertions, look for calls to the `xassert'
6259c2ec 487macros.) Any assertion that is reported to fail should be investigated.
3f715e77
EZ
488
489Building with GLYPH_DEBUG defined also defines several helper
490functions which can help debugging display code. One such function is
491`dump_glyph_matrix'. If you run Emacs under GDB, you can print the
492contents of any glyph matrix by just calling that function with the
493matrix as its argument. For example, the following command will print
6259c2ec 494the contents of the current matrix of the window whose pointer is in `w':
3f715e77
EZ
495
496 (gdb) p dump_glyph_matrix (w->current_matrix, 2)
497
498(The second argument 2 tells dump_glyph_matrix to print the glyphs in
499a long form.) You can dump the selected window's current glyph matrix
500interactively with "M-x dump-glyph-matrix RET"; see the documentation
501of this function for more details.
502
503Several more functions for debugging display code are available in
71d6b459
EZ
504Emacs compiled with GLYPH_DEBUG defined; type "C-h f dump- TAB" and
505"C-h f trace- TAB" to see the full list.
3f715e77 506
1ce9f40a
KS
507When you debug display problems running emacs under X, you can use
508the `ff' command to flush all pending display updates to the screen.
509
437368fe
EZ
510
511** Debugging LessTif
512
513If you encounter bugs whereby Emacs built with LessTif grabs all mouse
514and keyboard events, or LessTif menus behave weirdly, it might be
515helpful to set the `DEBUGSOURCES' and `DEBUG_FILE' environment
516variables, so that one can see what LessTif was doing at this point.
517For instance
177c0ea7 518
6806e867 519 export DEBUGSOURCES="RowColumn.c:MenuShell.c:MenuUtil.c"
437368fe 520 export DEBUG_FILE=/usr/tmp/LESSTIF_TRACE
2aa25884 521 emacs &
437368fe
EZ
522
523causes LessTif to print traces from the three named source files to a
2aa25884
EZ
524file in `/usr/tmp' (that file can get pretty large). The above should
525be typed at the shell prompt before invoking Emacs, as shown by the
526last line above.
437368fe
EZ
527
528Running GDB from another terminal could also help with such problems.
529You can arrange for GDB to run on one machine, with the Emacs display
530appearing on another. Then, when the bug happens, you can go back to
531the machine where you started GDB and use the debugger from there.
532
533
437368fe
EZ
534** Debugging problems which happen in GC
535
f46cc673
EZ
536The array `last_marked' (defined on alloc.c) can be used to display up
537to 500 last objects marked by the garbage collection process.
62578de5 538Whenever the garbage collector marks a Lisp object, it records the
1a527e27
EZ
539pointer to that object in the `last_marked' array, which is maintained
540as a circular buffer. The variable `last_marked_index' holds the
541index into the `last_marked' array one place beyond where the pointer
542to the very last marked object is stored.
437368fe
EZ
543
544The single most important goal in debugging GC problems is to find the
545Lisp data structure that got corrupted. This is not easy since GC
546changes the tag bits and relocates strings which make it hard to look
547at Lisp objects with commands such as `pr'. It is sometimes necessary
548to convert Lisp_Object variables into pointers to C struct's manually.
437368fe 549
1a527e27
EZ
550Use the `last_marked' array and the source to reconstruct the sequence
551that objects were marked. In general, you need to correlate the
552values recorded in the `last_marked' array with the corresponding
553stack frames in the backtrace, beginning with the innermost frame.
554Some subroutines of `mark_object' are invoked recursively, others loop
555over portions of the data structure and mark them as they go. By
556looking at the code of those routines and comparing the frames in the
557backtrace with the values in `last_marked', you will be able to find
558connections between the values in `last_marked'. E.g., when GC finds
559a cons cell, it recursively marks its car and its cdr. Similar things
560happen with properties of symbols, elements of vectors, etc. Use
561these connections to reconstruct the data structure that was being
562marked, paying special attention to the strings and names of symbols
563that you encounter: these strings and symbol names can be used to grep
564the sources to find out what high-level symbols and global variables
565are involved in the crash.
566
567Once you discover the corrupted Lisp object or data structure, grep
568the sources for its uses and try to figure out what could cause the
2fbcf174 569corruption. If looking at the sources doesn't help, you could try
1a527e27
EZ
570setting a watchpoint on the corrupted data, and see what code modifies
571it in some invalid way. (Obviously, this technique is only useful for
572data that is modified only very rarely.)
573
574It is also useful to look at the corrupted object or data structure in
575a fresh Emacs session and compare its contents with a session that you
576are debugging.
437368fe 577
93699019
EZ
578** Debugging problems with non-ASCII characters
579
580If you experience problems which seem to be related to non-ASCII
581characters, such as \201 characters appearing in the buffer or in your
582files, set the variable byte-debug-flag to t. This causes Emacs to do
583some extra checks, such as look for broken relations between byte and
584character positions in buffers and strings; the resulting diagnostics
585might pinpoint the cause of the problem.
586
036cb5a2
EZ
587** Debugging the TTY (non-windowed) version
588
589The most convenient method of debugging the character-terminal display
590is to do that on a window system such as X. Begin by starting an
591xterm window, then type these commands inside that window:
592
593 $ tty
594 $ echo $TERM
595
596Let's say these commands print "/dev/ttyp4" and "xterm", respectively.
597
598Now start Emacs (the normal, windowed-display session, i.e. without
599the `-nw' option), and invoke "M-x gdb RET emacs RET" from there. Now
600type these commands at GDB's prompt:
601
602 (gdb) set args -nw -t /dev/ttyp4
603 (gdb) set environment TERM xterm
604 (gdb) run
605
606The debugged Emacs should now start in no-window mode with its display
607directed to the xterm window you opened above.
608
e039053d
EZ
609Similar arrangement is possible on a character terminal by using the
610`screen' package.
611
19cf8f36
EZ
612** Running Emacs built with malloc debugging packages
613
614If Emacs exhibits bugs that seem to be related to use of memory
615allocated off the heap, it might be useful to link Emacs with a
616special debugging library, such as Electric Fence (a.k.a. efence) or
617GNU Checker, which helps find such problems.
618
619Emacs compiled with such packages might not run without some hacking,
620because Emacs replaces the system's memory allocation functions with
621its own versions, and because the dumping process might be
622incompatible with the way these packages use to track allocated
6259c2ec 623memory. Here are some of the changes you might find necessary:
19cf8f36 624
6259c2ec 625 - Edit configure, to set system_malloc and CANNOT_DUMP to "yes".
19cf8f36
EZ
626
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.
630
631 - Type "make" then "make -k install".
632
633 - If required, invoke the package-specific command to prepare
634 src/temacs for execution.
635
636 - cd ..; src/temacs
637
638(Note that this runs `temacs' instead of the usual `emacs' executable.
639This avoids problems with dumping Emacs mentioned above.)
640
641Some malloc debugging libraries might print lots of false alarms for
642bitfields used by Emacs in some data structures. If you want to get
643rid of the false alarms, you will have to hack the definitions of
644these data structures on the respective headers to remove the `:N'
645bitfield definitions (which will cause each such field to use a full
646int).
647
270bf00e
EZ
648** How to recover buffer contents from an Emacs core dump file
649
650The file etc/emacs-buffer.gdb defines a set of GDB commands for
651recovering the contents of Emacs buffers from a core dump file. You
652might also find those commands useful for displaying the list of
653buffers in human-readable format from within the debugger.
654
437368fe
EZ
655** Some suggestions for debugging on MS Windows:
656
657 (written by Marc Fleischeuers, Geoff Voelker and Andrew Innes)
658
3102e429 659To debug Emacs with Microsoft Visual C++, you either start emacs from
961e2394
EZ
660the debugger or attach the debugger to a running emacs process.
661
662To start emacs from the debugger, you can use the file bin/debug.bat.
663The Microsoft Developer studio will start and under Project, Settings,
3102e429 664Debug, General you can set the command-line arguments and Emacs's
437368fe
EZ
665startup directory. Set breakpoints (Edit, Breakpoints) at Fsignal and
666other functions that you want to examine. Run the program (Build,
667Start debug). Emacs will start and the debugger will take control as
668soon as a breakpoint is hit.
669
3102e429 670You can also attach the debugger to an already running Emacs process.
437368fe
EZ
671To do this, start up the Microsoft Developer studio and select Build,
672Start debug, Attach to process. Choose the Emacs process from the
673list. Send a break to the running process (Debug, Break) and you will
674find that execution is halted somewhere in user32.dll. Open the stack
675trace window and go up the stack to w32_msg_pump. Now you can set
676breakpoints in Emacs (Edit, Breakpoints). Continue the running Emacs
677process (Debug, Step out) and control will return to Emacs, until a
678breakpoint is hit.
679
3102e429 680To examine the contents of a Lisp variable, you can use the function
437368fe
EZ
681'debug_print'. Right-click on a variable, select QuickWatch (it has
682an eyeglass symbol on its button in the toolbar), and in the text
683field at the top of the window, place 'debug_print(' and ')' around
684the expression. Press 'Recalculate' and the output is sent to stderr,
685and to the debugger via the OutputDebugString routine. The output
686sent to stderr should be displayed in the console window that was
687opened when the emacs.exe executable was started. The output sent to
688the debugger should be displayed in the 'Debug' pane in the Output
689window. If Emacs was started from the debugger, a console window was
690opened at Emacs' startup; this console window also shows the output of
691'debug_print'.
692
693For example, start and run Emacs in the debugger until it is waiting
694for user input. Then click on the `Break' button in the debugger to
695halt execution. Emacs should halt in `ZwUserGetMessage' waiting for
696an 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
698this). Open the QuickWatch window and enter
699"debug_print(Vexec_path)". Evaluating this expression will then print
3102e429 700out the contents of the Lisp variable `exec-path'.
437368fe
EZ
701
702If QuickWatch reports that the symbol is unknown, then check the call
703stack in the `Call Stack' window. If the selected frame in the call
704stack is not an Emacs procedure, then the debugger won't recognize
705Emacs symbols. Instead, select a frame that is inside an Emacs
706procedure and try using `debug_print' again.
707
708If QuickWatch invokes debug_print but nothing happens, then check the
709thread that is selected in the debugger. If the selected thread is
710not the last thread to run (the "current" thread), then it cannot be
711used to execute debug_print. Use the Debug menu to select the current
712thread and try using debug_print again. Note that the debugger halts
713execution (e.g., due to a breakpoint) in the context of the current
714thread, so this should only be a problem if you've explicitly switched
715threads.
716
3102e429 717It is also possible to keep appropriately masked and typecast Lisp
437368fe
EZ
718symbols in the Watch window, this is more convenient when steeping
719though the code. For instance, on entering apply_lambda, you can
720watch (struct Lisp_Symbol *) (0xfffffff & args[0]).
961e2394
EZ
721
722Optimizations often confuse the MS debugger. For example, the
723debugger will sometimes report wrong line numbers, e.g., when it
724prints the backtrace for a crash. It is usually best to look at the
725disassembly to determine exactly what code is being run--the
726disassembly will probably show several source lines followed by a
727block of assembler for those lines. The actual point where Emacs
2fbcf174 728crashes will be one of those source lines, but not necessarily the one
961e2394
EZ
729that the debugger reports.
730
731Another problematic area with the MS debugger is with variables that
732are stored in registers: it will sometimes display wrong values for
733those variables. Usually you will not be able to see any value for a
734register variable, but if it is only being stored in a register
735temporarily, you will see an old value for it. Again, you need to
736look at the disassembly to determine which registers are being used,
737and look at those registers directly, to see the actual current values
738of these variables.
ab5796a9 739
bf69439f 740\f
5b87ad55
GM
741This file is part of GNU Emacs.
742
ab73e885 743GNU Emacs is free software: you can redistribute it and/or modify
5b87ad55 744it under the terms of the GNU General Public License as published by
ab73e885
GM
745the Free Software Foundation, either version 3 of the License, or
746(at your option) any later version.
5b87ad55
GM
747
748GNU Emacs is distributed in the hope that it will be useful,
749but WITHOUT ANY WARRANTY; without even the implied warranty of
750MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
751GNU General Public License for more details.
752
753You should have received a copy of the GNU General Public License
ab73e885 754along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
5b87ad55
GM
755
756\f
bf69439f
NR
757Local variables:
758mode: outline
759paragraph-separate: "[ \f]*$"
760end:
761