Getting A Backtrace

If Pidgin or Finch has crashed, before you submit a bug you should get a backtrace. Useful backtraces will help us find where in Pidgin, Finch, or LibPurple your bug exists, which will help us fix the bug.

Distribution-Specific Notes

Please follow the instructions here if you are using these distributions.

• Windows: see TipsForBugReports

• Ubuntu: see the ​Ubuntu wiki page on obtaining backtraces.
• Debian: see the ​Debian wiki page on obtaining backtraces.
• Fedora: Install the -debuginfo rpm first. See ​these instructions.
• Redhat: Install the -debuginfo rpm first, then follow our instructions below.
• Gentoo: emerge pidgin with USE=debug, and report the bug to Gentoo's bug tracker.
• Mandriva: Follow the instructions below, gdb will tell you which debug packages are missing, run gdb again after installation.
• Archlinux: see the ​http://wiki.archlinux.org/index.php/Debug_-_Getting_Traces, build debug version of pidgin and follow The Easy Way below.

The Easy Way

Before you follow these instructions, please make sure you have the debugging symbols for pidgin, libpurple, and finch installed (see the above instructions). If you can reproduce the crash, the easiest way to obtain a backtrace is by running with gdb. (Note that debugging finch requires a little more effort, see below.) Here are the basics:

   ~ $ gdb pidgin 2>&1 | tee ~/pidgin-backtrace.log

Next you'll see some information from gdb, similar to this:

   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)...

You will want to do two things now:

   (gdb) handle SIGPIPE nostop noprint
   (gdb) run

Information will pass by now. You should reproduce your crash now. Once the crash has happened, do the following:

   (gdb) bt full

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 Pidgin and so the backtrace won't end up being very useful after all. If you see function names, copy and paste all of the backtrace into your bug report. You'll want to be careful to make sure the wiki formatting doesn't butcher your pasted backtrace--you'll want to use the Preview button here.

Now you can exit gdb by typing quit:

   (gdb) quit
   ~ $

The Hard Way (a.k.a. Making Use of Core Files)

When an application crashes, it typically leaves a core file behind. In a console window when you run ls, you should see a file called core:

   ~ $ ls
   core

Sometimes this file is also called pidgin.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 the bash shell):

   ~ $ ulimit -c unlimited

If you have a core file, first check to make sure that it was created by Pidgin, by using file to examine it:

   ~ $ file core
   core: ELF 32-bit LSB core file of 'pidgin' (signal 11), Intel 80386, version 1, from 'pidgin'

The output of file may look different depending on your OS and hardware, but it should still be apparent that it was created by Pidgin.

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:

   ~ $ gdb pidgin core

At this point, you will see some information from gdb:

   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 `Pidgin'.
   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

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 No such file or directory, in which case you may have to give the full path to both Pidgin and the core file. Another reason would be if the core file isn't created by Pidgin, you may see a message saying warning: core file may not match specified executable file.

If gdb loaded Pidgin 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:

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

Now you'll want to get the backtrace. Type bt full at the prompt. gdb should then print a list of all the functions that were called leading up to the crash, and the values of some variables. 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 Pidgin 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 bug report. Be sure to also indicate what you were doing at the time.

Now you can exit gdb by typing quit:

   (gdb) quit
   ~ $

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 Pidgin, 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 Pidgin, since there's a good chance your bug will have been fixed.

GDB and finch

Because finch is a console-based application, running finch in gdb in a single terminal can lead to some quite bizarre effects. Assuming that finch will at least start up without crashing, you can attach gdb to a running finch process from a second terminal in order to debug it as you would Pidgin. Instead of following the instructions above ('gdb finch', then 'run'), start finch as you normally would in a terminal. Once it is up and running, open a second terminal and find its process ID using, e.g., the 'ps' command. Once you have its process ID, which we will call pid, run 'gdb finch pid ' in the second terminal. This should bring you to a (gdb) prompt, and the finch process will become unresponsive. Similar to before, run:

   (gdb) handle SIGPIPE nostop noprint
   (gdb) continue

Note the use of continue rather than run. From here on out, follow the directions above.

Additional Notes for Those Users Wanting To Do More

Often, you will see a backtrace where one or more of the top lines is in malloc() or g_malloc(). 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 MALLOC_CHECK_ to a value of 2. In bash this would be:

   export MALLOC_CHECK_=2

You can re-run pidgin inside gdb to get a new backtrace. Note that if you used a core file for getting a backtrace, this does not affect existing core files.