GDB Debugging: A quick introduction

This document contains a quick introduction on debugging using the GDB (GNU Debugger) commandline client. GDB, although not a graphical debugging client, is a very powerfull debugger. Like most Unix tools it has a pretty steep learning curve. This short tutorial like article will hopefully put you on the right track in order to debug your programs using GDB.

This article focusses on debugging within a Unix enviroment, using program examples in the C language. However, GDB is also supplied with the DJGPP package, which is a port of the GNU compiler-set for DOS and Windows. Using GDB under Dos is not much different from using it under Unix.

Before you will be able to debug your programs using GDB, you must first make sure that GDB knows how your program works. It must know the names and places of functions, variables and various other things. The info required is usually called the Debugging symbols. These debugging symbols are contained within your executable, and GDB can read them so it can provide you with an altogether better debugging experience.

Getting debugging symbols in your program is quite easy. If you are using a GNU compiler, for instance GCC, G77 or G++, you can simply supply the -g parameter during the compile run. This will tell the compiler to include debugging symbols in your program. I’m not sure if GDB will work with debugging symbols generated by other compilers. If you’ve got more than one source file which you compile into libs and then link them together, you should supply the -g parameter to each compile commandline.

An example. Suppose you have the following commandline to compile your program:

Then you should change it to read the following:

Starting the debugging session using GDB is as easy as:

This will place you at the GDB commandline and you are now ready to start debugging your program. The screen will look something like this:

GDB also contains a semi-ncurses interface. This interface will show you the current source code line/file which you are debugging. When the scope changes to another file, the display will automatically change too. Most people prefer some kind of visual feedback, and if you are one of them you can use the ncurses interface. Be advised though that it is quite buggy and will garble your display on more than one occasion. (Yay GNU). To start gdb with the ncurses interface you must specify the --tui commandline parameter when starting GDB.

Some other usefull options for GDB are:

As you might have seen in earlier examples, GDB is a command line interface. This means you will be provided with a prompt at which you can type commands. You might think this is arcane, and I won’t tell you you’re wrong. If you’re not comfortable with a command-line you should perhaps check out another debugging tool. But make no mistake: GDB is a very powerful tool. It is also available on most development machines and Operating Systems. So perhaps it is a good idea if you at least know how to perform basic debugging with it.

The GDB commandline looks like this:

Type your commands at this line. During debugging, GDB will provide you with basic knowledge about where you are debugging at the moment and the things that happen. When, for instance, I start the program, and it hits a breakpoint, GDB will display:

The first line shows what happened. A breakpoint was triggered in the executable at the position which corresponds to line 3 in the source of myprogram.c. The second line shows your current location in the source file. GDB has now stopped due to the breakpoint and is awaiting your every command.

Sometimes, GDB’s output may seem somewhat cryptic. This is probably because sometimes it simply is. You’ll get used to it.

A helpful tip might be that when you typed in a command once, you can then simply press the return/enter key to execute the last command you entered.

Some of the basic commands with which you control the GDB program are:

We’ve already seen how we can start the program being debugged. If you wish to stop it, you can simply switch to the debugging window (if you are debugging a graphical program) and press CTRL-C. This will break off the execution of the current program and show you some information about where you currently are.

If you wish to continue the program from the point where you pressed CTRL-C (or any other point where the program was interrupted), simply type cont.

Whenever the program is interrupted, you can use the backtrace command to see what functions have been called in order to bring you to the current location. This is especially neat when your program segfaults. A small example:

Suppose we have the following stupid program:

This program will produce a segmentation fault because you are trying to copy a string into a memory region (identified by 's') which has not been allocated. When the program is run, GDB will produce the following output:

This output is called a stack frame. The nice thing about this is that you can walk back through the functions that have been called (strcpy() and main()) and view variables in the scope of that function. Suppose the strcpy function was actually in a function named myfunc(), but the memory to which the strcpy function copies the string was (not) initialised in main(). You can now use the up and down to walk up and down the stack frame. When you enter a different stack frame you can view the contents of it’s variables by using print.

You can also supply the full parameter to the backtrace command. This will make backtrace automatically display all variable names and values in the scope of the stack frames.

One of the most important aspects of a debugger are breakpoints. In GDB you can set breakpoints with the appropriate break command. Breakpoints can be set on lines, functions or an address. Some examples:

An overview of breakpoint related commands:

Remember that the commands must work within the scope of the place where the breakpoint is set.

Sometimes it can be beneficial to watch the program executing step by step. This can help you pinpoint where exactly the program is producing errors or how it got to the part which is buggy. When stepping through a program, GDB will execute one line in the current scope of the source-code each time. There are two ways of stepping through a program:

Displaying data is a key aspect of debugging. The more you work with GDB, the more you will learn about displaying data and the better you will become at easier tracking down problems. GDB provides a number of ways in which you can view variable contents and other data.

You can use the print command to view the contents of variables and expressions. It’s usage is quite simply:

The expression can be a variable name, a calculation and even a function call. Remember that you can only access variables within the scope of the current stack frame. (See also the paragraph on 'Backtracing') When printing a value, GDB will show the address of the variable and it’s value. GDB is intelligent in that it automatically knows how to represent different variable types like string, integers, structs, arrays and floating point values. It is possible to use typecasting to show variables in different ways. For instance, to view the first character of a array of characters (otherwise known as a string), you can issue the command: print (char)*string, or more easily: print s[0]. If you would like to know the length of the string 's', you can issue a command like: print strlen(s).

You can specify formats in which the specified variables' value should be shown. Formats are available to more than just the print command. A format should be specified in the form of /[count][fmt] and should go between the print (or any other command which supports formats, like x) command and the variable you wish to print. count tells GDB to print the following count number of memory elements too. You can’t use count with the print command, but you CAN use it with x. FMT can be any of these formats:

Some examples

A more powerful command than print is the x command, which examines memory. It, too, supports formats (see print command). With x, the COUNT parameter of formats is very important. It allows you to view a block of memory in some kind of format. Here are some examples of 'x' usage:

In the above example we are displaying the memory region occupied by a string. The string has been initiated in the corresponding C code by allocating 20 characters to the 's' string. As we can see when we display the first 20 characters in this string that there isn’t a \0 character anywhere within the first 20 characters. This means that we have a buffer overrun, and thus a possible segmentation fault.

Use the display [EXPR] command to tell GDB to show a particular variables contents each time the program is interrupted (breakpoints, CTRL-C, etc). display works in the same way as x does. Expressions, once again, can be anything from a simple variable-name, an memory address and even a function. Use the undisplay command to stop displaying the data automatically. If you only want to temporary stop displaying, you may use the disable display and enable display commands. Both these commands require as a parameter the display rule. You can view all display rules by typing display without any parameters.

Changing data in a running program can be a very powerful tool. For example, one can use it to see what happens when you assign some daft value to a variable in your program. Does it crash, or does it handle it graceful? Or if you think you’ve finally found that nasty bug in your program and are preparing to change the code accordingly. You could first alter some variables to see if the fix you thought would bring an end to the suffering actually is the fix. Changing variables is also a great way to test all the possibilities in a routine. (There’s a name for this, but I forgot what it was. Something along the lines of touching every line of code?)

Changing data can be done with the set variable [EXPR] command. It’s a little confusing since set is also used to change options in GDB itself. Adding to the confusion: you can, in most cases, abbreviate the command and leave out the variable bit, so that the command becomes set [EXPR]

[EXPR] is an expression which assigns a value to a variable. For example, set my_linked_list = NULL. The expression must be valid within the current scope. For some reason it does not seem possible to use #define’d values in expressions. (If anybody can point out why this is, please let me know. It’s quite annoying) The expression should adhere to the syntax of the language the program you are debugging was written in. For C this would be set foo=5, for Pascal: set foo := 5.

You can also assign values to something called convenience variables. These variables are an extension of GDB and they are not part of the program that you are debugging. A convenience variable is prepended with a '$'. For example, set $prev_i = i;.

GDB has an enormous ammount of settings. Some of the more usefull ones are:

There are many more settings which you can change. Please see the 'Getting help' chapter for more information

GDB has lots of documentation, both in the GDB program itself as in various info and man pages.

Using the internal help system is easy. Type help at the command-line to get a overview of top-level help topics. Issue help [SUBTOPIC] to view the commands in that subtopic. To get help on a specific command, use help [COMMAND].

The info system on Unix systems holds the complete user manual for GDB, which is huge. Type info gdb at the commandline to view it. You might need a separate 400 page manual on how to use 'info' though. Some quick help: Press the enter key on anything which ends in '::' to follow that hyper-link. Use the 'l' key to return to the page which you were viewing before the current one.

You can also view the documentation online at http://sources.redhat.com/gdb/current/onlinedocs/gdb_toc.html.

Copyright (c) 2002-2004, Ferry Boender

This document may be freely distributed, in part or as a whole, on any medium, without the prior authorization of the author, provided that this Copyright notice remains intact, and there will be no obstruction as to the further distribution of this document. You may not ask a fee for the contents of this document, though a fee to compensate for the distribution of this document is permitted.

Modifications to this document are permitted, provided that the modified document is distributed under the same license as the original document and no copyright notices are removed from this document. All contents written by an author stays copyrighted by that author.

Failure to comply to one or all of the terms of this license automatically revokes your rights granted by this license

All brand and product names mentioned in this document are trademarks or registered trademarks of their respective holders.

Author: