Introduction to GDB Commands (GNAT User’s Guide for Native Platforms)

#### 6.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 that program as you read through the following section.

- `set args arguments`

    ‘arguments’ 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. You do not need the `set args` command 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. You can also specify program arguments on this command and if you specify `run` with no arguments, the arguments used on the previous command will be used again.

- `breakpoint location`

    This 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, which you specify in the format `file:linenumber`, or the name of a subprogram. If you request a breakpoint be set on a subprogram that is overloaded, either a prompt will ask you to specify on which of those subprograms you want to breakpoint or a breakpoint will be set on all of them. If the program is run and execution encounters the breakpoint, 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 you omit `name`, execution is suspended when any exception is raised.

- `print expression`

    This prints the value of the given expression. Most 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, the program executes that call and returns.

- `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. `emacs` has debugging modes that display both the relevant source and `GDB` commands and output. Successive applications of this command print subsequent lines. You can give this command an argument which is a line number, in which case it displays a few lines around the specified line.

- `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. You can use the command `up` 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. You may find this 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 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` and “bt” for `backtrace`) and only enough characters need be typed to disambiguate the command (e.g., “br” for `breakpoint`).