Completion (Debugging with GDB)

Next: Filename Arguments, Previous: Command Settings, Up: Commands [Contents][Index]

### 3.3 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, command options, 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 breTAB

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 the command you are trying to complete expects either a keyword or a number to follow, then ‘`NUMBER`’ will be shown among the available completions, for example:

    (gdb) print -elements TABTAB
    NUMBER     unlimited
    (gdb) print -elements

Here, the option expects a number (e.g., `100`), not literal `NUMBER`. Such metasyntactical arguments are always presented in uppercase.

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 `?`.

If the number of possible completions is large, GDB will print as much of the list as it has collected, as well as a message indicating that the list may be truncated.

    (gdb) b mTABTAB
    main
    <... the rest of the possible completions ...>
    *** List may be truncated, max-completions reached. ***
    (gdb) b m

This behavior can be controlled with the following commands:

`set max-completions limit`
`set max-completions unlimited`

  Set the maximum number of completion candidates. GDB will stop looking for more completions once it collects this many candidates. This is useful when completing on things like function names as collecting all the possible candidates can be time consuming. The default value is 200. A value of zero disables tab-completion. Note that setting either no limit or a very large limit can make completion slow.

`show max-completions`

  Show the maximum number of candidates that GDB will collect and show during completion.

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.

A likely situation where you might need this is in typing an expression that involves a C`++` symbol name with template parameters. This is because when completing expressions, GDB treats the ‘`<`’ character as word delimiter, assuming that it’s the less-than comparison operator (see C and C`++` Operators).

For example, when you want to call a C`++` template function interactively using the `print` or `call` commands, you may need to distinguish whether you mean the version of `name` that was specialized for `int`, `name<int>()`, or the version that was specialized for `float`, `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) p 'func<M-?
    func<int>()    func<float>()
    (gdb) p 'func<

When setting breakpoints however (see Location Specifications), you don’t usually need to type a quote before the function name, because GDB understands that you want to set a breakpoint on a function:

    (gdb) b func<M-?
    func<int>()    func<float>()
    (gdb) b func<

This is true even in the case of typing the name of C`++` overloaded functions (multiple definitions of the same function, distinguished by argument type). For example, when you want to set a breakpoint you don’t 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)`.

    (gdb) b bubble(M-?
    bubble(int)    bubble(double)
    (gdb) b bubble(douM-?
    bubble(double)

See quoting names for a description of other scenarios that require quoting.

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 tries3 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;
    }

#### Footnotes

### (3)

The completer can be confused by certain kinds of invalid expressions. Also, it only examines the static type of the expression, not the dynamic type.

Next: Filename Arguments, Previous: Command Settings, Up: Commands [Contents][Index]