Commit | Line | Data |
---|---|---|
a933dad1 | 1 | Debugging GNU Emacs |
5b87ad55 | 2 | |
acaf905b | 3 | Copyright (C) 1985, 2000-2012 Free Software Foundation, Inc. |
5b87ad55 | 4 | See 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 |
8 | read 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 |
11 | where the executable was made. That directory has a .gdbinit file |
12 | that defines various "user-defined" commands for debugging Emacs. | |
a313dc7b EZ |
13 | (These commands are described below under "Examining Lisp object |
14 | values" and "Debugging Emacs Redisplay problems".) | |
42a3c627 | 15 | |
70d9a9cd DK |
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. | |
22 | ||
42a3c627 | 23 | ** It is a good idea to run Emacs under GDB (or some other suitable |
437368fe EZ |
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.) | |
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 |
31 | kick 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 |
36 | All Lisp errors go through there. |
37 | ||
3102e429 | 38 | It is useful, when debugging, to have a guaranteed way to return to |
eb55f651 | 39 | the debugger at any time. When using X, this is easy: type C-z at the |
3102e429 EZ |
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. | |
43 | ||
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: | |
47 | ||
7718638c | 48 | handle SIGINT stop nopass |
3102e429 EZ |
49 | |
50 | After this `handle' command, SIGINT will return control to GDB. If | |
6259c2ec | 51 | you want the C-g to cause a QUIT within Emacs as well, omit the `nopass'. |
3102e429 EZ |
52 | |
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, | |
a933dad1 DL |
55 | |
56 | set stop_character = 29 | |
57 | ||
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. | |
63 | ||
06b6baf6 NR |
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. | |
8ef597fe | 68 | |
a933dad1 DL |
69 | ** Examining Lisp object values. |
70 | ||
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. | |
75 | ||
1ce9f40a KS |
76 | You can also use `pp value' to print the emacs value directly. |
77 | ||
11eced2f KS |
78 | To see the current value of a Lisp Variable, use `pv variable'. |
79 | ||
80 | Note: It is not a good idea to try `pr', `pp', or `pv' if you know that Emacs | |
1ce9f40a KS |
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', | |
437368fe EZ |
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. | |
86 | ||
3102e429 EZ |
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'. | |
a933dad1 | 92 | |
11eced2f KS |
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: | |
96 | ||
97 | p it->object | |
98 | xpr | |
99 | ||
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: | |
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 | ||
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.) | |
112 | ||
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. | |
116 | ||
437368fe | 117 | In general, most of the rest of the contents will be additional Lisp |
a933dad1 DL |
118 | objects which you can examine in turn with the x... commands. |
119 | ||
437368fe EZ |
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" | |
aa1f38cd NR |
123 | of the GDB manual to print values associated with the variable |
124 | called 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 | 131 | Then 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 |
148 | Now 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 | |
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: | |
157 | ||
158 | XVECTOR (this_command_keys)->contents[this_command_key_count++] = key; | |
159 | ||
f6e405a2 NR |
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)". | |
437368fe | 164 | |
f6e405a2 NR |
165 | When this information isn't available, you can use the xvector command in GDB |
166 | to 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 | ||
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 | |
6d02b70b | 180 | last 300 keystrokes. We can print this Lisp vector |
437368fe EZ |
181 | |
182 | p recent_keys | |
183 | pr | |
184 | ||
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 | |
188 | ||
189 | XVECTOR (recent_keys)->contents[recent_keys_index] = c; | |
190 | ||
191 | So we define a GDB command `xvector-elts', so the last 10 keystrokes | |
177c0ea7 | 192 | are printed by |
437368fe EZ |
193 | |
194 | xvector-elts recent_keys recent_keys_index 10 | |
195 | ||
196 | where 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 |
215 | The most convenient way is to use the `xbacktrace' command. This |
216 | shows the names of the Lisp functions that are currently active. | |
437368fe EZ |
217 | |
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: | |
223 | ||
224 | p *args | |
225 | pr | |
226 | ||
227 | This will print the name of the Lisp function called by that level | |
228 | of function calling. | |
229 | ||
230 | By printing the remaining elements of args, you can see the argument | |
231 | values. Here's how to print the first argument: | |
177c0ea7 | 232 | |
437368fe EZ |
233 | p args[1] |
234 | pr | |
235 | ||
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: | |
239 | ||
240 | p *args | |
241 | xtype | |
242 | ||
243 | and, assuming that "xtype" says that args[0] is a symbol: | |
244 | ||
177c0ea7 | 245 | xsymbol |
437368fe | 246 | |
11eced2f KS |
247 | ** Debugging Emacs Redisplay problems |
248 | ||
249 | The src/.gdbinit file defines many useful commands for dumping redisplay | |
250 | related 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 | ||
261 | The above commands also exist in a version with an `x' suffix which | |
262 | takes an object of the relevant type as argument. | |
263 | ||
6205d23a NR |
264 | ** Following longjmp call. |
265 | ||
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. | |
270 | ||
c167547b NR |
271 | ** Using GDB in Emacs |
272 | ||
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: | |
276 | ||
a313dc7b EZ |
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. | |
c167547b NR |
280 | |
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. | |
283 | ||
284 | 3) The STOP button on the tool bar is adjusted so that it sends SIGTSTP | |
285 | instead of the usual SIGINT. | |
286 | ||
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. | |
289 | ||
437368fe EZ |
290 | ** Debugging what happens while preloading and dumping Emacs |
291 | ||
292 | Type `gdb temacs' and start it with `r -batch -l loadup dump'. | |
293 | ||
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. | |
297 | ||
298 | ** Debugging `temacs' | |
299 | ||
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'. | |
303 | ||
304 | ** If you encounter X protocol errors | |
305 | ||
a2ebb43f RS |
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. | |
309 | ||
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. | |
437368fe | 315 | |
ec4054f0 EZ |
316 | You can start Emacs in a synchronous mode by invoking it with the -xrm |
317 | option, like this: | |
318 | ||
9031cdf2 | 319 | emacs -xrm "emacs.synchronous: true" |
ec4054f0 EZ |
320 | |
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. | |
324 | ||
1d3adc26 EZ |
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: | |
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 | ||
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/. | |
372 | ||
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. | |
380 | ||
437368fe EZ |
381 | ** If the symptom of the bug is that Emacs fails to respond |
382 | ||
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. | |
389 | ||
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. | |
394 | ||
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. | |
401 | ||
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. | |
407 | ||
0438ce91 DC |
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. | |
412 | ||
437368fe EZ |
413 | ** If certain operations in Emacs are slower than they used to be, here |
414 | is some advice for how to find out why. | |
415 | ||
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. | |
419 | ||
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. | |
423 | ||
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. | |
427 | ||
a933dad1 DL |
428 | ** If GDB does not run and your debuggers can't load Emacs. |
429 | ||
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 | |
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 | ||
444 | It is necessary to refer to the file `nmout' to convert | |
445 | numeric addresses into symbols and vice versa. | |
446 | ||
447 | It is useful to be running under a window system. | |
6259c2ec GM |
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. | |
a933dad1 DL |
451 | |
452 | ||
453 | ** Debugging incorrect screen updating. | |
454 | ||
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 | |
458 | ||
459 | (open-dribble-file "~/.dribble") | |
460 | (open-termscript "~/.termscript") | |
461 | ||
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. | |
466 | ||
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. | |
125f929e MB |
471 | |
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. | |
437368fe | 476 | |
3f715e77 EZ |
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: | |
481 | ||
482 | MYCPPFLAGS='-DGLYPH_DEBUG=1' make | |
483 | ||
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' | |
6259c2ec | 487 | macros.) Any assertion that is reported to fail should be investigated. |
3f715e77 EZ |
488 | |
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 | |
6259c2ec | 494 | the 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 | |
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. | |
502 | ||
503 | Several more functions for debugging display code are available in | |
71d6b459 EZ |
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. | |
3f715e77 | 506 | |
1ce9f40a KS |
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. | |
509 | ||
437368fe EZ |
510 | |
511 | ** Debugging LessTif | |
512 | ||
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 | |
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 | |
523 | causes LessTif to print traces from the three named source files to a | |
2aa25884 EZ |
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. | |
437368fe EZ |
527 | |
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. | |
532 | ||
533 | ||
437368fe EZ |
534 | ** Debugging problems which happen in GC |
535 | ||
f46cc673 EZ |
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. | |
62578de5 | 538 | Whenever the garbage collector marks a Lisp object, it records the |
1a527e27 EZ |
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. | |
437368fe EZ |
543 | |
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. | |
437368fe | 549 | |
1a527e27 EZ |
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. | |
566 | ||
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 | |
2fbcf174 | 569 | corruption. If looking at the sources doesn't help, you could try |
1a527e27 EZ |
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.) | |
573 | ||
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. | |
437368fe | 577 | |
93699019 EZ |
578 | ** Debugging problems with non-ASCII characters |
579 | ||
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. | |
586 | ||
036cb5a2 EZ |
587 | ** Debugging the TTY (non-windowed) version |
588 | ||
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: | |
592 | ||
593 | $ tty | |
594 | $ echo $TERM | |
595 | ||
596 | Let's say these commands print "/dev/ttyp4" and "xterm", respectively. | |
597 | ||
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: | |
601 | ||
602 | (gdb) set args -nw -t /dev/ttyp4 | |
603 | (gdb) set environment TERM xterm | |
604 | (gdb) run | |
605 | ||
606 | The debugged Emacs should now start in no-window mode with its display | |
607 | directed to the xterm window you opened above. | |
608 | ||
e039053d EZ |
609 | Similar 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 | ||
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. | |
618 | ||
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 | |
6259c2ec | 623 | memory. 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. | |
639 | This avoids problems with dumping Emacs mentioned above.) | |
640 | ||
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). | |
647 | ||
270bf00e EZ |
648 | ** How to recover buffer contents from an Emacs core dump file |
649 | ||
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. | |
654 | ||
437368fe EZ |
655 | ** Some suggestions for debugging on MS Windows: |
656 | ||
657 | (written by Marc Fleischeuers, Geoff Voelker and Andrew Innes) | |
658 | ||
3102e429 | 659 | To debug Emacs with Microsoft Visual C++, you either start emacs from |
961e2394 EZ |
660 | the debugger or attach the debugger to a running emacs process. |
661 | ||
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, | |
3102e429 | 664 | Debug, General you can set the command-line arguments and Emacs's |
437368fe EZ |
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. | |
669 | ||
3102e429 | 670 | You can also attach the debugger to an already running Emacs process. |
437368fe EZ |
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. | |
679 | ||
3102e429 | 680 | To 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 |
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'. | |
692 | ||
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 | |
3102e429 | 700 | out the contents of the Lisp variable `exec-path'. |
437368fe EZ |
701 | |
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. | |
707 | ||
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. | |
716 | ||
3102e429 | 717 | It is also possible to keep appropriately masked and typecast Lisp |
437368fe EZ |
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]). | |
961e2394 EZ |
721 | |
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 | |
2fbcf174 | 728 | crashes will be one of those source lines, but not necessarily the one |
961e2394 EZ |
729 | that the debugger reports. |
730 | ||
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. | |
ab5796a9 | 739 | |
bf69439f | 740 | \f |
5b87ad55 GM |
741 | This file is part of GNU Emacs. |
742 | ||
ab73e885 | 743 | GNU Emacs is free software: you can redistribute it and/or modify |
5b87ad55 | 744 | it under the terms of the GNU General Public License as published by |
ab73e885 GM |
745 | the Free Software Foundation, either version 3 of the License, or |
746 | (at your option) any later version. | |
5b87ad55 GM |
747 | |
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. | |
752 | ||
753 | You should have received a copy of the GNU General Public License | |
ab73e885 | 754 | along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. |
5b87ad55 GM |
755 | |
756 | \f | |
bf69439f NR |
757 | Local variables: |
758 | mode: outline | |
759 | paragraph-separate: "[ \f]*$" | |
760 | end: | |
761 |