8.1.3 Introduction to GDB Commands

GDB contains a large repertoire of commands. See Debugging with GDB for extensive documentation on the use of these commands, together with examples of their use. Furthermore, the command `help' invoked from within GDB activates a simple help facility which summarizes the available commands and their options. In this section we summarize a few of the most commonly used commands to give an idea of what GDB is about. You should create a simple program with debugging information and experiment with the use of these GDB commands on the program as you read through the following section.

• `set args `arguments`'

  The arguments list above is a list of arguments to be passed to the program on a subsequent run command, just as though the arguments had been entered on a normal invocation of the program. The set args command is not needed if the program does not require arguments.

• `run'

  The run command causes execution of the program to start from the beginning. If the program is already running, that is to say if you are currently positioned at a breakpoint, then a prompt will ask for confirmation that you want to abandon the current execution and restart.

• `breakpoint `location`'

  The breakpoint command sets a breakpoint, that is to say a point at which execution will halt and GDB will await further commands. location is either a line number within a file, given in the format file:linenumber, or it is the name of a subprogram. If you request that a breakpoint be set on a subprogram that is overloaded, a prompt will ask you to specify on which of those subprograms you want to breakpoint. You can also specify that all of them should be breakpointed. If the program is run and execution encounters the breakpoint, then the program stops and GDB signals that the breakpoint was encountered by printing the line of code before which the program is halted.

• `catch exception `name`'

  This command causes the program execution to stop whenever exception name is raised. If name is omitted, then the execution is suspended when any exception is raised.

• `print `expression`'

  This will print the value of the given expression. Most simple Ada expression formats are properly handled by GDB, so the expression can contain function calls, variables, operators, and attribute references.

• `continue'

  Continues execution following a breakpoint, until the next breakpoint or the termination of the program.

• `step'

  Executes a single line after a breakpoint. If the next statement is a subprogram call, execution continues into (the first statement of) the called subprogram.

• `next'

  Executes a single line. If this line is a subprogram call, executes and returns from the call.

• `list'

  Lists a few lines around the current source location. In practice, it is usually more convenient to have a separate edit window open with the relevant source file displayed. Successive applications of this command print subsequent lines. The command can be given an argument which is a line number, in which case it displays a few lines around the specified one.

• `backtrace'

  Displays a backtrace of the call chain. This command is typically used after a breakpoint has occurred, to examine the sequence of calls that leads to the current breakpoint. The display includes one line for each activation record (frame) corresponding to an active subprogram.

• `up'

  At a breakpoint, GDB can display the values of variables local to the current frame. The command up can be used to examine the contents of other active frames, by moving the focus up the stack, that is to say from callee to caller, one frame at a time.

• `down'

  Moves the focus of GDB down from the frame currently being examined to the frame of its callee (the reverse of the previous command),

• `frame `n`'

  Inspect the frame with the given number. The value 0 denotes the frame of the current breakpoint, that is to say the top of the call stack.

• `kill'

  Kills the child process in which the program is running under GDB. This may be useful for several purposes:

  • It allows you to recompile and relink your program, since on many systems you cannot regenerate an executable file while it is running in a process.
  • You can run your program outside the debugger, on systems that do not permit executing a program outside GDB while breakpoints are set within GDB.
  • It allows you to debug a core dump rather than a running process.

The above list is a very short introduction to the commands that GDB provides. Important additional capabilities, including conditional breakpoints, the ability to execute command sequences on a breakpoint, the ability to debug at the machine instruction level and many other features are described in detail in Debugging with GDB. Note that most commands can be abbreviated (for example, c for continue, bt for backtrace).