/emacs/trunk

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