$page->title = 'GDB Help';

require('template.inc.php');

<h1>What is a backtrace?</h1>

So Gaim crashed on you again, huh? I'm sorry to hear that. Maybe you can help

prevent it from happening again. To diagnose the problem, we need to know the

last few functions that were called before Gaim crashed. This output is

called a "backtrace."

<h2>The Easy Way</h2>

If you are able to reproduce the crash, the easiest way to obtain a backtrace is by doing

the following:

<code>[mark@diverge mark]$ <b>gdb gaim</b>

GNU gdb Red Hat Linux (5.3post-0.20021129.18rh)

Copyright 2003 Free Software Foundation, Inc.

GDB is free software, covered by the GNU General Public License, and you are

welcome to change it and/or distribute copies of it under certain conditions.

Type "show copying" to see the conditions.

There is absolutely no warranty for GDB. Type "show warranty" for details.

This GDB was configured as "i386-redhat-linux-gnu"...

(no debugging symbols found)...

(gdb) <b>handle SIGPIPE nostop</b>

(gdb) <b>run</b>

<i>(stuff scrolls by)</i>

<i><b>(do whatever it is you did to get Gaim to crash)</b></i>

(gdb) <b>bt full</b>

<i>(the bt scrolls by)</i>

<i><b>(copy and paste all of this to your bug report)</b></i>

(gdb) <b>quit</b>

[mark@diverge mark]$</code>

<h2>The Hard Way</h2>

<h3>or <i>"How To Make Use Of A Core File"</i></h3>

When a program crashes it typically leaves a core file behind. In a console

window when you run <code>ls</code>, you should see a file called

<code>core</code>:

<code>~ $ <b>ls</b>

core</code>

Sometimes this file is also called gaim.core or something similar, depending

on what OS you use and what your settings are. If you don't see this file,

it's possible that it's in a different location, and you should look at the

settings for your OS to see where it might be. It's also possible that the

core file was not created at all; this would happen if your system was

configured not to leave a core file. Often you just need to tell your shell

to not restrict the size of core files (this may only work for bash):

<code>~ $ <b>ulimit -c unlimited</b></code>

If you have a core file, first check to make sure that it was created by gaim,

by using <code>file</code> to examine it:

<code>~ $ <b>file core</b>

core: ELF 32-bit LSB core file of 'gaim' (signal 11), Intel 80386, version 1, from 'gaim'</code>

The output of <code>file</code> may look different depending on your OS and

hardware, but it should still be apparent that it was created by gaim.

Now that you have the core file, you'll want to get the useful information out

of it. In order to do that, you'll have to open it in GDB. GDB stands for GNU

DeBugger, and is a very useful programmer's tool. It needs to know which

application created the core file and what the core file name is, so run:

<code>~ $ <b>gdb gaim core</b></code>

If you use the applet version of gaim, you should use <code>gaim_applet</code>

instead of <code>gaim</code> when running <code>gdb</code>. You don't have to

give the full path to the <code>gaim</code>/<code>gaim_applet</code> binary as

long as it is in your PATH environment variable (i.e. if you can run

<code>gaim</code> and have it work, you don't need the full path). You do,

however, have to specify the correct name of the core file. At this point, gdb

should start printing information about what it's doing:

<code>GNU gdb 5.0

Copyright 2000 Free Software Foundation, Inc.

GDB is free software, covered by the GNU General Public License, and you are

welcome to change it and/or distribute copies of it under certain conditions.

Type "show copying" to see the conditions.

There is absolutely no warranty for GDB. Type "show warranty" for details.

This GDB was configured as "i686-pc-linux-gnu"...

Core was generated by `gaim'.

Program terminated with signal 11, Segmentation fault.

Reading symbols from /usr/lib/libesd.so.0...done.

Loaded symbols for /usr/lib/libesd.so.0

Reading symbols from /lib/libm.so.6...done.

Loaded symbols for /lib/libm.so.6</code>

And so forth. There are a couple reasons why you might see something other

than this. One reason is if gdb can't find something it needs, it might give a

warning such as <code>"No such file or directory."</code>, in which case you

may have to give the full path to both gaim and the core file. Another reason

would be if the core file isn't created by gaim, you may see a message saying

"warning: core file may not match specified executable file."

If gdb loaded gaim and the core file successfully, then once it's done loading

all the symbols that it will need, it should print the information from the

top of the stack, and prompt you:

<code>#0 0x404f1140 in poll () from /lib/libc.so.6

(gdb)</code>

Now you'll want to get the backtrace. At the prompt, type either

<code>backtrace</code> or <code>bt</code>. gdb should then print a list of

all the functions that were called leading up to the crash:

<code>(gdb) <b>backtrace</b>

#0 0x404f1140 in poll () from /lib/libc.so.6

#1 0x40325f99 in g_main_poll (timeout=-1, use_priority=0, priority=0) at gmain.c:1034

#2 0x4032594d in g_main_iterate (block=1, dispatch=1) at gmain.c:808

#3 0x40325cfc in g_main_run (loop=0x81becb0) at gmain.c:935

#4 0x4023b4b7 in gtk_main () at gtkmain.c:524

#5 0x805b131 in main (argc=1, argv=0xbffffa94) at aim.c:669

#6 0x4044938b in __libc_start_main () from /lib/libc.so.6

(gdb)</code>

When you get the backtrace, instead of seeing function names, you might see

'??' instead. If that's the case, gdb couldn't read the function names from

gaim and the core file, and so the core file won't end up being very useful

after all. However, if you were able to see the function names, then copy all

of the output from the backtrace and post a <a href="bug.php">bug report</a>.

Be sure to also indicate what you were doing at the time.

Now you can exit gdb by typing <code>quit</code>:

<code>(gdb) <b>quit</b>

~ $</code>

There may be other useful information that can be retrieved from the core

file, such as the values of variables. For this reason it's a good idea to

keep the core file. If you upgrade Gaim, the core file will no longer match

the binary, and it won't be useful anymore; however, don't let that stop you

from upgrading Gaim, since there's a good chance your bug will have been

fixed.

<h2>Distribution Notes</h2>

<li>Debian: see http://wiki.debian.net/?HowToGetABacktrace</li>

<li>Fedora: Install the -debug rpm first</li>

<li>Redhat: Install the -debug rpm first</li>

<li>Gentoo: emerge gaim with USE=debug</li>

<h2>Additional notes for those who want to do more</h2>

Often, you will see a backtrace where one or more of the top lines is in

<code>malloc()</code> or <code>g_malloc()</code>. When this happens, chances

are your backtrace isn't very useful. The easiest way to find some useful

information is to set the environment variable <code>MALLOC_CHECK_</code> to

a value of 2. In bash this would be</p>

<pre><code>export MALLOC_CHECK_=2</code></pre>

You can re-run gaim inside gdb to get a new backtrace. Note, this does not

affect existing core files.