Debugging with GDB: Commands

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 3. GDB Commands

You can abbreviate a GDB command to the first few letters of the command name, if that abbreviation is unambiguous; and you can repeat certain GDB commands by typing just `RET`. You can also use the `TAB` key to get GDB to fill out the rest of a word in a command (or to show you the alternatives available, if there is more than one possibility).

> 3.1 Command Syntax |  | How to give commands to GDB
> 3.2 Command Completion |  | Command completion
> 3.3 Getting Help |  | How to ask GDB for help

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 3.1 Command Syntax

A GDB command is a single line of input. There is no limit on how long it can be. It starts with a command name, which is followed by arguments whose meaning depends on the command name. For example, the command `step` accepts an argument which is the number of times to step, as in ``step 5'`. You can also use the `step` command with no arguments. Some commands do not allow any arguments.

GDB command names may always be truncated if that abbreviation is unambiguous. Other possible command abbreviations are listed in the documentation for individual commands. In some cases, even ambiguous abbreviations are allowed; for example, `s` is specially defined as equivalent to `step` even though there are other commands whose names start with `s`. You can test abbreviations by using them as arguments to the `help` command.

A blank line as input to GDB (typing just `RET`) means to repeat the previous command. Certain commands (for example, `run`) will not repeat this way; these are commands whose unintentional repetition might cause trouble and which you are unlikely to want to repeat. User-defined commands can disable this feature; see dont-repeat.

The `list` and `x` commands, when you repeat them with `RET`, construct new arguments rather than repeating exactly as typed. This permits easy scanning of source or memory.

GDB can also use `RET` in another way: to partition lengthy output, in a way similar to the common utility `more` (see section Screen Size). Since it is easy to press one `RET` too many in this situation, GDB disables command repetition after any command that generates this sort of display.

Any text from a `#` to the end of the line is a comment; it does nothing. This is useful mainly in command files (see section Command Files).

The `Ctrl-o` binding is useful for repeating a complex sequence of commands. This command accepts the current line, like `RET`, and then fetches the next line relative to the current line from the history for editing.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 3.2 Command Completion

GDB can fill in the rest of a word in a command for you, if there is only one possibility; it can also show you what the valid possibilities are for the next word in a command, at any time. This works for GDB commands, GDB subcommands, and the names of symbols in your program.

Press the `TAB` key whenever you want GDB to fill out the rest of a word. If there is only one possibility, GDB fills in the word, and waits for you to finish the command (or press `RET` to enter it). For example, if you type

    (gdb) info bre TAB

GDB fills in the rest of the word ``breakpoints'`, since that is the only `info` subcommand beginning with ``bre'`:

    (gdb) info breakpoints

You can either press `RET` at this point, to run the `info breakpoints` command, or backspace and enter something else, if ``breakpoints'` does not look like the command you expected. (If you were sure you wanted `info breakpoints` in the first place, you might as well just type `RET` immediately after ``info bre'`, to exploit command abbreviations rather than command completion).

If there is more than one possibility for the next word when you press `TAB`, GDB sounds a bell. You can either supply more characters and try again, or just press `TAB` a second time; GDB displays all the possible completions for that word. For example, you might want to set a breakpoint on a subroutine whose name begins with ``make_'`, but when you type `b make_`TAB`` GDB just sounds the bell. Typing `TAB` again displays all the function names in your program that begin with those characters, for example:

    (gdb) b make_ TAB
    GDB sounds bell; press TAB again, to see:
    make_a_section_from_file     make_environ
    make_abs_section             make_function_type
    make_blockvector             make_pointer_type
    make_cleanup                 make_reference_type
    make_command                 make_symbol_completion_list
    (gdb) b make_

After displaying the available possibilities, GDB copies your partial input (``b make_'` in the example) so you can finish the command.

If you just want to see the list of alternatives in the first place, you can press `M-?` rather than pressing `TAB` twice. `M-?` means ``META` ?`. You can type this either by holding down a key designated as the `META` shift on your keyboard (if there is one) while typing `?`, or as `ESC` followed by `?`.

Sometimes the string you need, while logically a "word", may contain parentheses or other characters that GDB normally excludes from its notion of a word. To permit word completion to work in this situation, you may enclose words in `'` (single quote marks) in GDB commands.

The most likely situation where you might need this is in typing the name of a C`++` function. This is because C`++` allows function overloading (multiple definitions of the same function, distinguished by argument type). For example, when you want to set a breakpoint you may need to distinguish whether you mean the version of `name` that takes an `int` parameter, `name(int)`, or the version that takes a `float` parameter, `name(float)`. To use the word-completion facilities in this situation, type a single quote `'` at the beginning of the function name. This alerts GDB that it may need to consider more information than usual when you press `TAB` or `M-?` to request word completion:

    (gdb) b 'bubble( M-?
    bubble(double,double)    bubble(int,int)
    (gdb) b 'bubble(

In some cases, GDB can tell that completing a name requires using quotes. When this happens, GDB inserts the quote for you (while completing as much as it can) if you do not type the quote in the first place:

    (gdb) b bub TAB
    GDB alters your input line to the following, and rings a bell:
    (gdb) b 'bubble(

In general, GDB can tell that a quote is needed (and inserts it) if you have not yet started typing the argument list when you ask for completion on an overloaded symbol.

For more information about overloaded functions, see C`++` Expressions. You can use the command `set overload-resolution off` to disable overload resolution; see GDB Features for C`++`.

When completing in an expression which looks up a field in a structure, GDB also tries(2) to limit completions to the field names available in the type of the left-hand-side:

    (gdb) p gdb_stdout.M-?
    magic                to_fputs             to_rewind
    to_data              to_isatty            to_write
    to_delete            to_put               to_write_async_safe
    to_flush             to_read

This is because the `gdb_stdout` is a variable of the type `struct ui_file` that is defined in GDB sources as follows:

    struct ui_file
    {
       int *magic;
       ui_file_flush_ftype *to_flush;
       ui_file_write_ftype *to_write;
       ui_file_write_async_safe_ftype *to_write_async_safe;
       ui_file_fputs_ftype *to_fputs;
       ui_file_read_ftype *to_read;
       ui_file_delete_ftype *to_delete;
       ui_file_isatty_ftype *to_isatty;
       ui_file_rewind_ftype *to_rewind;
       ui_file_put_ftype *to_put;
       void *to_data;
    }

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 3.3 Getting Help

You can always ask GDB itself for information on its commands, using the command `help`.

`help`
`h`
  You can use `help` (abbreviated `h`) with no arguments to display a short list of named classes of commands:

      (gdb) help
      List of classes of commands:

      aliases -- Aliases of other commands
      breakpoints -- Making program stop at certain points
      data -- Examining data
      files -- Specifying and examining files
      internals -- Maintenance commands
      obscure -- Obscure features
      running -- Running the program
      stack -- Examining the stack
      status -- Status inquiries
      support -- Support facilities
      tracepoints -- Tracing of program execution without
                     stopping the program
      user-defined -- User-defined commands

      Type "help" followed by a class name for a list of
      commands in that class.
      Type "help" followed by command name for full
      documentation.
      Command name abbreviations are allowed if unambiguous.
      (gdb)

`help class`
  Using one of the general help classes as an argument, you can get a list of the individual commands in that class. For example, here is the help display for the class `status`:

      (gdb) help status
      Status inquiries.

      List of commands:

      info -- Generic command for showing things
              about the program being debugged
      show -- Generic command for showing things
              about the debugger

      Type "help" followed by command name for full
      documentation.
      Command name abbreviations are allowed if unambiguous.
      (gdb)

`help command`
  With a command name as `help` argument, GDB displays a short paragraph on how to use that command.

`apropos args`
  The `apropos` command searches through all of the GDB commands, and their documentation, for the regular expression specified in args. It prints out all matches found. For example:

      apropos alias

  results in:

      alias -- Define a new command that is an alias of an existing command
      aliases -- Aliases of other commands
      d -- Delete some breakpoints or auto-display expressions
      del -- Delete some breakpoints or auto-display expressions
      delete -- Delete some breakpoints or auto-display expressions

`complete args`
  The `complete args` command lists all the possible completions for the beginning of a command. Use args to specify the beginning of the command you want completed. For example:

      complete i

  results in:

      if
      ignore
      info
      inspect

  This is intended for use by GNU Emacs.

In addition to `help`, you can use the GDB commands `info` and `show` to inquire about the state of your program, or the state of GDB itself. Each command supports many topics of inquiry; this manual introduces each of them in the appropriate context. The listings under `info` and under `show` in the Command, Variable, and Function Index point to all the sub-commands. See section Command, Variable, and Function Index.

`info`
  This command (abbreviated `i`) is for describing the state of your program. For example, you can show the arguments passed to a function with `info args`, list the registers currently in use with `info registers`, or list the breakpoints you have set with `info breakpoints`. You can get a complete list of the `info` sub-commands with `help info`.

`set`
  You can assign the result of an expression to an environment variable with `set`. For example, you can set the GDB prompt to a $-sign with `set prompt $`.

`show`
  In contrast to `info`, `show` is for describing the state of GDB itself. You can change most of the things you can `show`, by using the related command `set`; for example, you can control what number system is used for displays with `set radix`, or simply inquire which is currently in use with `show radix`.

  To display all the settable parameters and their current values, you can use `show` with no arguments; you may also use `info set`. Both commands produce the same display.

Here are several miscellaneous `show` subcommands, all of which are exceptional in lacking corresponding `set` commands:

`show version`
  Show what version of GDB is running. You should include this information in GDB bug-reports. If multiple versions of GDB are in use at your site, you may need to determine which version of GDB you are running; as GDB evolves, new commands are introduced, and old ones may wither away. Also, many system vendors ship variant versions of GDB, and there are variant versions of GDB in GNU/Linux distributions as well. The version number is the same as the one announced when you start GDB.

`show copying`
`info copying`
  Display information about permission for copying GDB.

`show warranty`
`info warranty`
  Display the GNU "NO WARRANTY" statement, or a warranty, if your version of GDB comes with one.

`show configuration`
  Display detailed information about the way GDB was configured when it was built. This displays the optional arguments passed to the ``configure'` script and also configuration parameters detected automatically by `configure`. When reporting a GDB bug (see section 31. Reporting Bugs in GDB), it is important to include this information in your report.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by GNAT Mailserver on April, 17 2014 using texi2html