SDB:Debugging with Glibc

Version: 7.0

Debugging your applications with glibc

This article describes some of the features of the GNU C library (glibc 2.1) version 2.1 (or higher), which will prove very useful when debugging applications and libraries. These features offer additional debugging possibilities that normal debuggers like gdb or trace utilities like strace and ltrace do not provide.

A glibc manual documenting most of these areas is already available. Therefore, some references to the manual will be made in order to avoid redundant information. In some other cases, however, this article represents the only information source so far.

Debugging Malloc-related problems

The malloc implementation in glibc is less robust than other malloc implementations, particularly regarding faulty calls. On the other hand, it presents important advantages in terms of thread security, speed, and lower memory requirements. For instance, segmentation faults may occur if a pointer is released more than once by using the free function, or if the allocated space is overwritten by just one byte. Nevertheless, this feature contributes to find bugs, too.

Just for clarification purposes: A segmentation fault in one of the malloc routines such as __free or chunk_alloc is always the result of a wrong usage of the malloc routines. Therefore, it makes no sense to complain about bugs in malloc routines - these are always (at least so far ;-) due to bugs in the application program.

In addition to the segmentation faults, glibc includes numerous tools to debug malloc-related problems. However, most of these tools require the recompilation of the affected programs.

Consistency checks

By setting the environment variable MALLOC_CHECK_ (the final underscore is very important and should not be omitted), you can trouble-shoot the use of malloc, realloc, and free. If MALLOC_CHECK_ is already set, a special (although less efficient) implementation will be used. It allows simple errors such as repeated calls of free with the same argument, or overruns of a single byte (off-by-one bugs). However, this method does not guarantee protection against all bugs, and memory leaks might occur.

If MALLOC_CHECK_ is set to 0, any detected heap corruption will be ignored without being registered. If it is set to 1, a diagnostic will be logged in stderr. If set to 2, abort will be immediately executed. This can be very useful because, otherwise, a system crash might subsequently occur and the true cause for it would be very difficult to track down.

Another possibility is compiling special memory checks in your program. For further details, please refer to the glibc manual (which can be displayed with e.g. info libc "Heap Consistency Checking").

Searching for memory leaks

Finding memory leaks (i.e. the allocation of non-released memory) by hand is quite difficult, since it implies checking all malloc and free calls (even indirect). Glibc includes a tool named mtrace that enables to search for memory leaks automatically. A detailed description of this tool can be found in the glibc manual. In order to read the corresponding section, please enter info libc "Allocation Debugging".

Creating a stack trace

If a program is terminated with a segmentation fault, you can create a stack trace by using the command catchsegv. You simply need to add the program producing the segmentation fault as argument of catchsegv: e.g., catchsegv buggy.

The backtrace function of <execinfo.h> can be used to create a stack trace in your own programs.

Problems with dynamic link libraries

In order to debug the dynamic linking of programs, the dynamic linker can be instructed to output different kinds of debugging messages. The debugging output is controlled through the environment variable LD_DEBUG. A list of options will be displayed when LD_DEBUG is set to help. For example, the output of LD_DEBUG=help ls is:

Valid options for the LD_DEBUG environment variable are:

  bindings  display information about symbol binding
  files     display processing of files and libraries
  help      display this help message and exit
  libs      display library search paths
  reloc     display relocation processing
  symbols   display symbol table processing
  versions  display version dependencies

To direct the debugging output into a file instead of standard output
a filename can be specified using the LD_DEBUG_OUTPUT environment variable.

If you want to use more than one option, please separate them by commas, e.g. LD_DEBUG=files,libs program.

The program ldd produces a list of all libraries required by a program or library. <keyword>Debugging,Malloc,glibc</keyword>