Debugging with GDB ¶

2.1 Invoking GDB ¶

Invoke GDB by running the program gdb. Once started, GDB reads commands from the terminal until you tell it to exit.

You can also run gdb with a variety of arguments and options, to specify more of your debugging environment at the outset.

The command-line options described here are designed to cover a variety of situations; in some environments, some of these options may effectively be unavailable.

The most usual way to start GDB is with one argument, specifying an executable program:

gdb program

You can also start with both an executable program and a core file specified:

gdb program core

You can, instead, specify a process ID as a second argument or use option -p, if you want to debug a running process:

gdb program 1234
gdb -p 1234

would attach GDB to process 1234. With option -p you can omit the program filename.

Taking advantage of the second command-line argument requires a fairly complete operating system; when you use GDB as a remote debugger attached to a bare board, there may not be any notion of “process”, and there is often no way to get a core dump. GDB will warn you if it is unable to attach or to read core dumps.

You can optionally have gdb pass any arguments after the executable file to the inferior using --args. This option stops option processing.

gdb --args gcc -O2 -c foo.c

This will cause gdb to debug gcc, and to set gcc’s command-line arguments (see Your Program’s Arguments) to ‘-O2 -c foo.c’.

You can run gdb without printing the front material, which describes GDB’s non-warranty, by specifying --silent (or -q/--quiet):

gdb --silent

You can further control how GDB starts up by using command-line options. GDB itself can remind you of the options available.

Type

gdb -help

to display all available options and briefly describe their use (‘gdb -h’ is a shorter equivalent).

All options and command line arguments you give are processed in sequential order. The order makes a difference when the ‘-x’ option is used.

• Choosing Files
• Choosing Modes
• What GDB Does During Startup
• Initialization Files

2.2 Quitting GDB ¶

quit [expression] ¶

exit [expression]

q

To exit GDB, use the quit command (abbreviated q), the exit command, or type an end-of-file character (usually Ctrl-d). If you do not supply expression, GDB will terminate normally; otherwise it will terminate using the result of expression as the error code.

An interrupt (often Ctrl-c) does not exit from GDB, but rather terminates the action of any GDB command that is in progress and returns to GDB command level. It is safe to type the interrupt character at any time because GDB does not allow it to take effect until a time when it is safe.

If you have been using GDB to control an attached process or device, you can release it with the detach command (see Debugging an Already-running Process).

2.3 Shell Commands ¶

If you need to execute occasional shell commands during your debugging session, there is no need to leave or suspend GDB; you can just use the shell command.

shell command-string ¶

!command-string

Invoke a shell to execute command-string. Note that no space is needed between ! and command-string. On GNU and Unix systems, the environment variable SHELL, if it exists, determines which shell to run. Otherwise GDB uses the default shell (/bin/sh on GNU and Unix systems, cmd.exe on MS-Windows, COMMAND.COM on MS-DOS, etc.).

You may also invoke shell commands from expressions, using the $_shell convenience function. See $_shell convenience function.

The utility make is often needed in development environments. You do not have to use the shell command for this purpose in GDB:

make make-args ¶

Execute the make program with the specified arguments. This is equivalent to ‘shell make make-args’.

pipe [command] | shell_command

| [command] | shell_command

pipe -d delim command delim shell_command

| -d delim command delim shell_command

Executes command and sends its output to shell_command. Note that no space is needed around |. If no command is provided, the last command executed is repeated.

In case the command contains a |, the option -d delim can be used to specify an alternate delimiter string delim that separates the command from the shell_command.

Example:

(gdb) p var
$1 = {
  black = 144,
  red = 233,
  green = 377,
  blue = 610,
  white = 987
}

(gdb) pipe p var|wc
      7      19      80
(gdb) |p var|wc -l
7

(gdb) p /x var
$4 = {
  black = 0x90,
  red = 0xe9,
  green = 0x179,
  blue = 0x262,
  white = 0x3db
}
(gdb) ||grep red
  red => 0xe9,

(gdb) | -d ! echo this contains a | char\n ! sed -e 's/|/PIPE/'
this contains a PIPE char
(gdb) | -d xxx echo this contains a | char!\n xxx sed -e 's/|/PIPE/'
this contains a PIPE char!
(gdb)

The convenience variables $_shell_exitcode and $_shell_exitsignal can be used to examine the exit status of the last shell command launched by shell, make, pipe and |. See Convenience Variables.

2.4 Logging Output ¶

You may want to save the output of GDB commands to a file. There are several commands to control GDB’s logging.

set logging enabled [on|off] ¶

Enable or disable logging.

set logging file file

Change the name of the current logfile. The default logfile is gdb.txt.

set logging overwrite [on|off]

By default, GDB will append to the logfile. Set overwrite if you want set logging enabled on to overwrite the logfile instead.

set logging redirect [on|off]

By default, GDB output will go to both the terminal and the logfile. Set redirect if you want output to go only to the log file.

set logging debugredirect [on|off]

By default, GDB debug output will go to both the terminal and the logfile. Set debugredirect if you want debug output to go only to the log file.

show logging

Show the current values of the logging settings.

You can also redirect the output of a GDB command to a shell command. See pipe.

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

3.2 Command Settings ¶

Many commands change their behavior according to command-specific variables or settings. These settings can be changed with the set subcommands. For example, the print command (see Examining Data) prints arrays differently depending on settings changeable with the commands set print elements NUMBER-OF-ELEMENTS and set print array-indexes, among others.

You can change these settings to your preference in the gdbinit files loaded at GDB startup. See What GDB Does During Startup.

The settings can also be changed interactively during the debugging session. For example, to change the limit of array elements to print, you can do the following:

(gdb) set print elements 10
(gdb) print some_array
$1 = {0, 10, 20, 30, 40, 50, 60, 70, 80, 90...}

The above set print elements 10 command changes the number of elements to print from the default of 200 to 10. If you only intend this limit of 10 to be used for printing some_array, then you must restore the limit back to 200, with set print elements 200.

Some commands allow overriding settings with command options. For example, the print command supports a number of options that allow overriding relevant global print settings as set by set print subcommands. See print options. The example above could be rewritten as:

(gdb) print -elements 10 -- some_array
$1 = {0, 10, 20, 30, 40, 50, 60, 70, 80, 90...}

Alternatively, you can use the with command to change a setting temporarily, for the duration of a command invocation.

with setting [value] [-- command] ¶

w setting [value] [-- command]

Temporarily set setting to value for the duration of command.

setting is any setting you can change with the set subcommands. value is the value to assign to setting while running command.

If no command is provided, the last command executed is repeated.

If a command is provided, it must be preceded by a double dash (--) separator. This is required because some settings accept free-form arguments, such as expressions or filenames.

For example, the command

(gdb) with print array on -- print some_array

is equivalent to the following 3 commands:

(gdb) set print array on
(gdb) print some_array
(gdb) set print array off

The with command is particularly useful when you want to override a setting while running user-defined commands, or commands defined in Python or Guile. See Extending GDB.

(gdb) with print pretty on -- my_complex_command

To change several settings for the same command, you can nest with commands. For example, with language ada -- with print elements 10 temporarily changes the language to Ada and sets a limit of 10 elements to print for arrays and strings.

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 tries³ 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;
}

3.4 Filenames As Command Arguments ¶

When passing filenames (or directory names) as arguments to a command, if the filename argument does not include any whitespace, double quotes, or single quotes, then for all commands the filename can be written as a simple string, for example:

(gdb) file /path/to/some/file

If the filename does include whitespace, double quotes, or single quotes, then GDB has two approaches for how these filenames should be formatted; which format to use depends on which command is being used.

Most GDB commands don’t require, or support, quoting and escaping. These commands treat any text after the command name, that is not a command option (see Command options), as the filename, even if the filename contains whitespace or quote characters. In the following example the user is adding /path/that contains/two spaces/ to the auto-load safe-path (see add-auto-load-safe-path):

(gdb) add-auto-load-safe-path /path/that contains/two spaces/

A small number of commands require that filenames containing whitespace or quote characters are either quoted, or have the special characters escaped with a backslash. Commands that support this style are marked as such in the manual, any command not marked as accepting quoting and escaping of its filename argument, does not accept this filename argument style.

For example, to load the file /path/with spaces/to/a file with the file command (see Commands to Specify Files), you can escape the whitespace characters with a backslash:

(gdb) file /path/with\ spaces/to/a\ file

Alternatively the entire filename can be wrapped in either single or double quotes, in which case no backlsashes are needed, for example:

(gdb) symbol-file "/path/with spaces/to/a file"
(gdb) exec-file '/path/with spaces/to/a file'

It is possible to include a quote character within a quoted filename by escaping it with a backslash, for example, within a filename surrounded by double quotes, a double quote character should be escaped with a backslash, but a single quote character should not be escaped. Within a single quoted string a single quote character needs to be escaped, but a double quote character does not.

A literal backslash character can also be included by escaping it with a backslash.

3.5 Command options ¶

Some commands accept options starting with a leading dash. For example, print -pretty. Similarly to command names, you can abbreviate a GDB option to the first few letters of the option name, if that abbreviation is unambiguous, and you can also use the TAB key to get GDB to fill out the rest of a word in an option (or to show you the alternatives available, if there is more than one possibility).

Some commands take raw input as argument. For example, the print command processes arbitrary expressions in any of the languages supported by GDB. With such commands, because raw input may start with a leading dash that would be confused with an option or any of its abbreviations, e.g. print -p (short for print -pretty or printing negative p?), if you specify any command option, then you must use a double-dash (--) delimiter to indicate the end of options.

Some options are described as accepting an argument which can be either on or off. These are known as boolean options. Similarly to boolean settings commands—on and off are the typical values, but any of 1, yes and enable can also be used as “true” value, and any of 0, no and disable can also be used as “false” value. You can also omit a “true” value, as it is implied by default.

For example, these are equivalent:

(gdb) print -object on -pretty off -element unlimited -- *myptr
(gdb) p -o -p 0 -e u -- *myptr

You can discover the set of options some command accepts by completing on - after the command name. For example:

(gdb) print -TABTAB
-address         -max-depth               -object          -static-members
-array           -memory-tag-violations   -pretty          -symbol
-array-indexes   -nibbles                 -raw-values      -union
-elements        -null-stop               -repeats         -vtbl

Completion will in some cases guide you with a suggestion of what kind of argument an option expects. For example:

(gdb) print -elements TABTAB
NUMBER     unlimited

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

(For more on using the print command, see Examining Data.)

3.6 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 -- User-defined 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. If a command has aliases, the aliases are given after the command name, separated by commas. If an alias has default arguments, the full definition of the alias is given after the first line. For example, here is the help display for the class status:

(gdb) help status
Status inquiries.

List of commands:

info, inf, i -- Generic command for showing things
        about the program being debugged
info address, iamain  -- Describe where symbol SYM is stored.
  alias iamain = info address main
info all-registers -- List of all registers and their contents,
        for selected stack frame.
...
show, info set -- 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. If that command has one or more aliases, GDB will display a first line with the command name and all its aliases separated by commas. This first line will be followed by the full definition of all aliases having default arguments. When asking the help for an alias, the documentation for the aliased command is shown.

A user-defined alias can optionally be documented using the document command (see document). GDB then considers this alias as different from the aliased command: this alias is not listed in the aliased command help output, and asking help for this alias will show the documentation provided for the alias instead of the documentation of the aliased command.

apropos [-v] regexp ¶

The apropos command searches through all of the GDB commands and aliases, and their documentation, for the regular expression specified in args. It prints out all matches found. The optional flag ‘-v’, which stands for ‘verbose’, indicates to output the full documentation of the matching commands and highlight the parts of the documentation matching regexp. For example:

apropos alias

results in:

alias -- Define a new command that is an alias of an existing command
aliases -- User-defined aliases of other commands

while

apropos -v cut.*thread apply

results in the below output, where ‘cut for 'thread apply’ is highlighted if styling is enabled.

taas -- Apply a command to all threads (ignoring errors
and empty output).
Usage: taas COMMAND
shortcut for 'thread apply all -s COMMAND'

tfaas -- Apply a command to all frames of all threads
(ignoring errors and empty output).
Usage: tfaas COMMAND
shortcut for 'thread apply all -s frame apply all -s COMMAND'

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 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 Reporting Bugs in GDB), it is important to include this information in your report.

4.1 Compiling for Debugging ¶

In order to debug a program effectively, you need to generate debugging information when you compile it. This debugging information is stored in the object file; it describes the data type of each variable or function and the correspondence between source line numbers and addresses in the executable code.

To request debugging information, specify the ‘-g’ option when you run the compiler.

Programs that are to be shipped to your customers are compiled with optimizations, using the ‘-O’ compiler option. However, some compilers are unable to handle the ‘-g’ and ‘-O’ options together. Using those compilers, you cannot generate optimized executables containing debugging information.

GCC, the GNU C/C++ compiler, supports ‘-g’ with or without ‘-O’, making it possible to debug optimized code. We recommend that you always use ‘-g’ whenever you compile a program. You may think your program is correct, but there is no sense in pushing your luck. For more information, see Debugging Optimized Code.

Older versions of the GNU C compiler permitted a variant option ‘-gg’ for debugging information. GDB no longer supports this format; if your GNU C compiler has this option, do not use it.

GDB knows about preprocessor macros and can show you their expansion (see C Preprocessor Macros). Most compilers do not include information about preprocessor macros in the debugging information if you specify the -g flag alone. Version 3.1 and later of GCC, the GNU C compiler, provides macro information if you are using the DWARF debugging format, and specify the option -g3.

See Options for Debugging Your Program or GCC in Using the GNU Compiler Collection (GCC), for more information on GCC options affecting debug information.

You will have the best debugging experience if you use the latest version of the DWARF debugging format that your compiler supports. DWARF is currently the most expressive and best supported debugging format in GDB.

4.2 Starting your Program ¶

run ¶

r

Use the run command to start your program under GDB. You must first specify the program name with an argument to GDB (see Getting In and Out of GDB), or by using the file or exec-file command (see Commands to Specify Files).

If you are running your program in an execution environment that supports processes, run creates an inferior process and makes that process run your program. In some environments without processes, run jumps to the start of your program. Other targets, like ‘remote’, are always running. If you get an error message like this one:

The "remote" target does not support "run".
Try "help target" or "continue".

then use continue to run your program. You may need load first (see load).

The execution of a program is affected by certain information it receives from its superior. GDB provides ways to specify this information, which you must do before starting your program. (You can change it after starting your program, but such changes only affect your program the next time you start it.) This information may be divided into four categories:

The arguments.

Specify the arguments to give your program as the arguments of the run command. If a shell is available on your target, the shell is used to pass the arguments, so that you may use normal conventions (such as wildcard expansion or variable substitution) in describing the arguments. In Unix systems, you can control which shell is used with the SHELL environment variable. If you do not define SHELL, GDB uses the default shell (/bin/sh). You can disable use of any shell with the set startup-with-shell command (see below for details).

The environment.

Your program normally inherits its environment from GDB, but you can use the GDB commands set environment and unset environment to change parts of the environment that affect your program. See Your Program’s Environment.

The working directory.

You can set your program’s working directory with the command set cwd. If you do not set any working directory with this command, your program will inherit GDB’s working directory if native debugging, or the remote server’s working directory if remote debugging. See Your Program’s Working Directory.

The standard input and output.

Your program normally uses the same device for standard input and standard output as GDB is using. You can redirect input and output in the run command line, or you can use the tty command to set a different device for your program. See Your Program’s Input and Output.

Warning: While input and output redirection work, you cannot use pipes to pass the output of the program you are debugging to another program; if you attempt this, GDB is likely to wind up debugging the wrong program.

When you issue the run command, your program begins to execute immediately. See Stopping and Continuing, for discussion of how to arrange for your program to stop. Once your program has stopped, you may call functions in your program, using the print or call commands. See Examining Data.

If the modification time of your symbol file has changed since the last time GDB read its symbols, GDB discards its symbol table, and reads it again. When it does this, GDB tries to retain your current breakpoints.

start ¶

The name of the main procedure can vary from language to language. With C or C++, the main procedure name is always main, but other languages such as Ada do not require a specific name for their main procedure. The debugger provides a convenient way to start the execution of the program and to stop at the beginning of the main procedure, depending on the language used.

The ‘start’ command does the equivalent of setting a temporary breakpoint at the beginning of the main procedure and then invoking the ‘run’ command.

Some programs contain an elaboration phase where some startup code is executed before the main procedure is called. This depends on the languages used to write your program. In C++, for instance, constructors for static and global objects are executed before main is called. It is therefore possible that the debugger stops before reaching the main procedure. However, the temporary breakpoint will remain to halt execution.

Specify the arguments to give to your program as arguments to the ‘start’ command. These arguments will be given verbatim to the underlying ‘run’ command. Note that the same arguments will be reused if no argument is provided during subsequent calls to ‘start’ or ‘run’.

It is sometimes necessary to debug the program during elaboration. In these cases, using the start command would stop the execution of your program too late, as the program would have already completed the elaboration phase. Under these circumstances, either insert breakpoints in your elaboration code before running your program or use the starti command.

starti ¶

The ‘starti’ command does the equivalent of setting a temporary breakpoint at the first instruction of a program’s execution and then invoking the ‘run’ command. For programs containing an elaboration phase, the starti command will stop execution at the start of the elaboration phase.

set exec-wrapper wrapper ¶

show exec-wrapper

unset exec-wrapper

When ‘exec-wrapper’ is set, the specified wrapper is used to launch programs for debugging. GDB starts your program with a shell command of the form exec wrapper program. Quoting is added to program and its arguments, but not to wrapper, so you should add quotes if appropriate for your shell. The wrapper runs until it executes your program, and then GDB takes control.

You can use any program that eventually calls execve with its arguments as a wrapper. Several standard Unix utilities do this, e.g. env and nohup. Any Unix shell script ending with exec "$@" will also work.

For example, you can use env to pass an environment variable to the debugged program, without setting the variable in your shell’s environment:

(gdb) set exec-wrapper env 'LD_PRELOAD=libtest.so'
(gdb) run

This command is available when debugging locally on most targets, excluding DJGPP, Cygwin, MS Windows, and QNX Neutrino.

set startup-with-shell

set startup-with-shell on

set startup-with-shell off

show startup-with-shell

On Unix systems, by default, if a shell is available on your target, GDB) uses it to start your program. Arguments of the run command are passed to the shell, which does variable substitution, expands wildcard characters and performs redirection of I/O. In some circumstances, it may be useful to disable such use of a shell, for example, when debugging the shell itself or diagnosing startup failures such as:

(gdb) run
Starting program: ./a.out
During startup program terminated with signal SIGSEGV, Segmentation fault.

which indicates the shell or the wrapper specified with ‘exec-wrapper’ crashed, not your program. Most often, this is caused by something odd in your shell’s non-interactive mode initialization file—such as .cshrc for C-shell, $.zshenv for the Z shell, or the file specified in the BASH_ENV environment variable for BASH.

set auto-connect-native-target ¶

set auto-connect-native-target on

set auto-connect-native-target off

show auto-connect-native-target

By default, if the current inferior is not connected to any target yet (e.g., with target remote), the run command starts your program as a native process under GDB, on your local machine. If you’re sure you don’t want to debug programs on your local machine, you can tell GDB to not connect to the native target automatically with the set auto-connect-native-target off command.

If on, which is the default, and if the current inferior is not connected to a target already, the run command automatically connects to the native target, if one is available.

If off, and if the current inferior is not connected to a target already, the run command fails with an error:

(gdb) run
Don't know how to run.  Try "help target".

If the current inferior is already connected to a target, GDB always uses it with the run command.

In any case, you can explicitly connect to the native target with the target native command. For example,

(gdb) set auto-connect-native-target off
(gdb) run
Don't know how to run.  Try "help target".
(gdb) target native
(gdb) run
Starting program: ./a.out
[Inferior 1 (process 10421) exited normally]

In case you connected explicitly to the native target, GDB remains connected even if all inferiors exit, ready for the next run command. Use the disconnect command to disconnect.

Examples of other commands that likewise respect the auto-connect-native-target setting: attach, info proc, info os.

set disable-randomization ¶

set disable-randomization on

This option (enabled by default in GDB) will turn off the native randomization of the virtual address space of the started program. This option is useful for multiple debugging sessions to make the execution better reproducible and memory addresses reusable across debugging sessions.

This feature is implemented only on certain targets, including GNU/Linux. On GNU/Linux you can get the same behavior using

(gdb) set exec-wrapper setarch `uname -m` -R

set disable-randomization off

Leave the behavior of the started executable unchanged. Some bugs rear their ugly heads only when the program is loaded at certain addresses. If your bug disappears when you run the program under GDB, that might be because GDB by default disables the address randomization on platforms, such as GNU/Linux, which do that for stand-alone programs. Use set disable-randomization off to try to reproduce such elusive bugs.

On targets where it is available, virtual address space randomization protects the programs against certain kinds of security attacks. In these cases the attacker needs to know the exact location of a concrete executable code. Randomizing its location makes it impossible to inject jumps misusing a code at its expected addresses.

Prelinking shared libraries provides a startup performance advantage but it makes addresses in these libraries predictable for privileged processes by having just unprivileged access at the target system. Reading the shared library binary gives enough information for assembling the malicious code misusing it. Still even a prelinked shared library can get loaded at a new random address just requiring the regular relocation process during the startup. Shared libraries not already prelinked are always loaded at a randomly chosen address.

Position independent executables (PIE) contain position independent code similar to the shared libraries and therefore such executables get loaded at a randomly chosen address upon startup. PIE executables always load even already prelinked shared libraries at a random address. You can build such executable using gcc -fPIE -pie.

Heap (malloc storage), stack and custom mmap areas are always placed randomly (as long as the randomization is enabled).

show disable-randomization

Show the current setting of the explicit disable of the native randomization of the virtual address space of the started program.

4.3 Your Program’s Arguments ¶

The arguments to your program can be specified by the arguments of the run command. They are passed to a shell, which expands wildcard characters and performs redirection of I/O, and thence to your program. Your SHELL environment variable (if it exists) specifies what shell GDB uses. If you do not define SHELL, GDB uses the default shell (/bin/sh on Unix).

On non-Unix systems, the program is usually invoked directly by GDB, which emulates I/O redirection via the appropriate system calls, and the wildcard characters are expanded by the startup code of the program, not by the shell.

run with no arguments uses the same arguments used by the previous run, or those set by the set args command.

set args ¶

Specify the arguments to be used the next time your program is run. If set args has no arguments, run executes your program with no arguments. Once you have run your program with arguments, using set args before the next run is the only way to run it again without arguments.

show args ¶

Show the arguments to give your program when it is started.

4.4 Your Program’s Environment ¶

The environment consists of a set of environment variables and their values. Environment variables conventionally record such things as your user name, your home directory, your terminal type, and your search path for programs to run. Usually you set up environment variables with the shell and they are inherited by all the other programs you run. When debugging, it can be useful to try running your program with a modified environment without having to start GDB over again.

path directory ¶

Add directory to the front of the PATH environment variable (the search path for executables) that will be passed to your program. The value of PATH used by GDB does not change. You may specify several directory names, separated by whitespace or by a system-dependent separator character (‘:’ on Unix, ‘;’ on MS-DOS and MS-Windows). If directory is already in the path, it is moved to the front, so it is searched sooner.

You can use the string ‘$cwd’ to refer to whatever is the current working directory at the time GDB searches the path. If you use ‘.’ instead, it refers to the directory where you executed the path command. GDB replaces ‘.’ in the directory argument (with the current path) before adding directory to the search path.

show paths ¶

Display the list of search paths for executables (the PATH environment variable).

show environment [varname] ¶

Print the value of environment variable varname to be given to your program when it starts. If you do not supply varname, print the names and values of all environment variables to be given to your program. You can abbreviate environment as env.

set environment varname [=value]

Set environment variable varname to value. The value changes for your program (and the shell GDB uses to launch it), not for GDB itself. The value may be any string; the values of environment variables are just strings, and any interpretation is supplied by your program itself. The value parameter is optional; if it is eliminated, the variable is set to a null value.

For example, this command:

set env USER = foo

tells the debugged program, when subsequently run, that its user is named ‘foo’. (The spaces around ‘=’ are used for clarity here; they are not actually required.)

Note that on Unix systems, GDB runs your program via a shell, which also inherits the environment set with set environment. If necessary, you can avoid that by using the ‘env’ program as a wrapper instead of using set environment. See set exec-wrapper, for an example doing just that.

Environment variables that are set by the user are also transmitted to gdbserver to be used when starting the remote inferior. see QEnvironmentHexEncoded.

unset environment varname

Remove variable varname from the environment to be passed to your program. This is different from ‘set env varname =’; unset environment removes the variable from the environment, rather than assigning it an empty value.

Environment variables that are unset by the user are also unset on gdbserver when starting the remote inferior. see QEnvironmentUnset.

Warning: On Unix systems, GDB runs your program using the shell indicated by your SHELL environment variable if it exists (or /bin/sh if not). If your SHELL variable names a shell that runs an initialization file when started non-interactively—such as .cshrc for C-shell, $.zshenv for the Z shell, or the file specified in the BASH_ENV environment variable for BASH—any variables you set in that file affect your program. You may wish to move setting of environment variables to files that are only run when you sign on, such as .login or .profile.

4.5 Your Program’s Working Directory ¶

Each time you start your program with run, the inferior will be initialized with the current working directory specified by the set cwd command. If no directory has been specified by this command, then the inferior will inherit GDB’s current working directory as its working directory if native debugging, or it will inherit the remote server’s current working directory if remote debugging.

set cwd [directory]

Set the inferior’s working directory to directory, which will be glob-expanded in order to resolve tildes (~). If no argument has been specified, the command clears the setting and resets it to an empty state. This setting has no effect on GDB’s working directory, and it only takes effect the next time you start the inferior. The ~ in directory is a short for the home directory, usually pointed to by the HOME environment variable. On MS-Windows, if HOME is not defined, GDB uses the concatenation of HOMEDRIVE and HOMEPATH as fallback.

You can also change GDB’s current working directory by using the cd command. See cd command.

show cwd ¶

Show the inferior’s working directory. If no directory has been specified by set cwd, then the default inferior’s working directory is the same as GDB’s working directory.

cd [directory]

Set the GDB working directory to directory. If not given, directory uses '~'.

The GDB working directory serves as a default for the commands that specify files for GDB to operate on. See Commands to Specify Files. See set cwd command.

pwd ¶

Print the GDB working directory.

It is generally impossible to find the current working directory of the process being debugged (since a program can change its directory during its run). If you work on a system where GDB supports the info proc command (see Process Information), you can use the info proc command to find out the current working directory of the debuggee.

4.6 Your Program’s Input and Output ¶

By default, the program you run under GDB does input and output to the same terminal that GDB uses. GDB switches the terminal to its own terminal modes to interact with you, but it records the terminal modes your program was using and switches back to them when you continue running your program.

info terminal ¶

Displays information recorded by GDB about the terminal modes your program is using.

You can redirect your program’s input and/or output using shell redirection with the run command. For example,

run > outfile

starts your program, diverting its output to the file outfile.

Another way to specify where your program should do input and output is with the tty command. This command accepts a file name as argument, and causes this file to be the default for future run commands. It also resets the controlling terminal for the child process, for future run commands. For example,

tty /dev/ttyb

directs that processes started with subsequent run commands default to do input and output on the terminal /dev/ttyb and have that as their controlling terminal.

An explicit redirection in run overrides the tty command’s effect on the input/output device, but not its effect on the controlling terminal.

When you use the tty command or redirect input in the run command, only the input for your program is affected. The input for GDB still comes from your terminal. tty is an alias for set inferior-tty.

You can use the show inferior-tty command to tell GDB to display the name of the terminal that will be used for future runs of your program.

set inferior-tty [ tty ] ¶

Set the tty for the program being debugged to tty. Omitting tty restores the default behavior, which is to use the same terminal as GDB.

show inferior-tty ¶

Show the current tty for the program being debugged.

4.7 Debugging an Already-running Process ¶

attach process-id

This command attaches to a running process—one that was started outside GDB. (info files shows your active targets.) The command takes as argument a process ID. The usual way to find out the process-id of a Unix process is with the ps utility, or with the ‘jobs -l’ shell command.

attach does not repeat if you press RET a second time after executing the command.

To use attach, your program must be running in an environment which supports processes; for example, attach does not work for programs on bare-board targets that lack an operating system. You must also have permission to send the process a signal.

When you use attach, the debugger finds the program running in the process first by looking in the current working directory, then (if the program is not found) by using the source file search path (see Specifying Source Directories). You can also use the file command to load the program. See Commands to Specify Files.

If the debugger can determine that the executable file running in the process it is attaching to does not match the current exec-file loaded by GDB, the option exec-file-mismatch specifies how to handle the mismatch. GDB tries to compare the files by comparing their build IDs (see build ID), if available.

set exec-file-mismatch ‘ask|warn|off’ ¶

Whether to detect mismatch between the current executable file loaded by GDB and the executable file used to start the process. If ‘ask’, the default, display a warning and ask the user whether to load the process executable file; if ‘warn’, just display a warning; if ‘off’, don’t attempt to detect a mismatch. If the user confirms loading the process executable file, then its symbols will be loaded as well.

show exec-file-mismatch ¶

Show the current value of exec-file-mismatch.

The first thing GDB does after arranging to debug the specified process is to stop it. You can examine and modify an attached process with all the GDB commands that are ordinarily available when you start processes with run. You can insert breakpoints; you can step and continue; you can modify storage. If you would rather the process continue running, you may use the continue command after attaching GDB to the process.

detach ¶

When you have finished debugging the attached process, you can use the detach command to release it from GDB control. Detaching the process continues its execution. After the detach command, that process and GDB become completely independent once more, and you are ready to attach another process or start one with run. detach does not repeat if you press RET again after executing the command.

If you exit GDB while you have an attached process, you detach that process. If you use the run command, you kill that process. By default, GDB asks for confirmation if you try to do either of these things; you can control whether or not you need to confirm by using the set confirm command (see Optional Warnings and Messages).

4.8 Killing the Child Process ¶

kill ¶

Kill the child process in which your program is running under GDB.

This command is useful if you wish to debug a core dump instead of a running process. GDB ignores any core dump file while your program is running.

On some operating systems, a program cannot be executed outside GDB while you have breakpoints set on it inside GDB. You can use the kill command in this situation to permit running your program outside the debugger.

The kill command is also useful if you wish to recompile and relink your program, since on many systems it is impossible to modify an executable file while it is running in a process. In this case, when you next type run, GDB notices that the file has changed, and reads the symbol table again (while trying to preserve your current breakpoint settings).

4.9 Debugging Multiple Inferiors Connections and Programs ¶

GDB lets you run and debug multiple programs in a single session. In addition, GDB on some systems may let you run several programs simultaneously (otherwise you have to exit from one before starting another). On some systems GDB may even let you debug several programs simultaneously on different remote systems. In the most general case, you can have multiple threads of execution in each of multiple processes, launched from multiple executables, running on different machines.

GDB represents the state of each program execution with an object called an inferior. An inferior typically corresponds to a process, but is more general and applies also to targets that do not have processes. Inferiors may be created before a process runs, and may be retained after a process exits. Inferiors have unique identifiers that are different from process ids. Usually each inferior will also have its own distinct address space, although some embedded targets may have several inferiors running in different parts of a single address space. Each inferior may in turn have multiple threads running in it.

The commands info inferiors and info connections, which will be introduced below, accept a space-separated ID list as their argument specifying one or more elements on which to operate. A list element can be either a single non-negative number, like ‘5’, or an ascending range of such numbers, like ‘5-7’. A list can consist of any combination of such elements, even duplicates or overlapping ranges are valid. E.g. ‘1 4-6 5 4-4’ or ‘1 2 4-7’.

To find out what inferiors exist at any moment, use info inferiors:

info inferiors ¶

Print a list of all inferiors currently being managed by GDB. By default all inferiors are printed, but the ID list id… can be used to limit the display to just the requested inferiors.

GDB displays for each inferior (in this order):

1. the inferior number assigned by GDB
2. the target system’s inferior identifier
3. the target connection the inferior is bound to, including the unique connection number assigned by GDB, and the protocol used by the connection.
4. the name of the executable the inferior is running.

An asterisk ‘*’ preceding the GDB inferior number indicates the current inferior.

For example,

(gdb) info inferiors
  Num  Description       Connection                      Executable
* 1    process 3401      1 (native)                      goodbye
  2    process 2307      2 (extended-remote host:10000)  hello

To get information about the current inferior, use inferior:

inferior ¶

Shows information about the current inferior.

For example,

(gdb) inferior
[Current inferior is 1 [process 3401] (helloworld)]

To find out what open target connections exist at any moment, use info connections:

info connections ¶

Print a list of all open target connections currently being managed by GDB. By default all connections are printed, but the ID list id… can be used to limit the display to just the requested connections.

GDB displays for each connection (in this order):

1. the connection number assigned by GDB.
2. the protocol used by the connection.
3. a textual description of the protocol used by the connection.

An asterisk ‘*’ preceding the connection number indicates the connection of the current inferior.

For example,

(gdb) info connections
  Num  What                        Description
* 1    extended-remote host:10000  Extended remote serial target in gdb-specific protocol
  2    native                      Native process
  3    core                        Local core dump file

To switch focus between inferiors, use the inferior command:

inferior infno ¶

Make inferior number infno the current inferior. The argument infno is the inferior number assigned by GDB, as shown in the first field of the ‘info inferiors’ display.

The debugger convenience variable ‘$_inferior’ contains the number of the current inferior. You may find this useful in writing breakpoint conditional expressions, command scripts, and so forth. See Convenience Variables, for general information on convenience variables.

You can get multiple executables into a debugging session via the add-inferior and clone-inferior commands. On some systems GDB can add inferiors to the debug session automatically by following calls to fork and exec. To remove inferiors from the debugging session use the remove-inferiors command.

add-inferior [ -copies n ] [ -exec executable ] [-no-connection ] ¶

Adds n inferiors to be run using executable as the executable; n defaults to 1. If no executable is specified, the inferiors begins empty, with no program. You can still assign or change the program assigned to the inferior at any time by using the file command with the executable name as its argument.

By default, the new inferior begins connected to the same target connection as the current inferior. For example, if the current inferior was connected to gdbserver with target remote, then the new inferior will be connected to the same gdbserver instance. The ‘-no-connection’ option starts the new inferior with no connection yet. You can then for example use the target remote command to connect to some other gdbserver instance, use run to spawn a local program, etc.

clone-inferior [ -copies n ] [ infno ] ¶

Adds n inferiors ready to execute the same program as inferior infno; n defaults to 1, and infno defaults to the number of the current inferior. This command copies the values of the args, inferior-tty and cwd properties from the current inferior to the new one. It also propagates changes the user made to environment variables using the set environment and unset environment commands. This is a convenient command when you want to run another instance of the inferior you are debugging.

(gdb) info inferiors
  Num  Description       Connection   Executable
* 1    process 29964     1 (native)   helloworld
(gdb) clone-inferior
Added inferior 2.
1 inferiors added.
(gdb) info inferiors
  Num  Description       Connection   Executable
* 1    process 29964     1 (native)   helloworld
  2    <null>            1 (native)   helloworld

You can now simply switch focus to inferior 2 and run it.

remove-inferiors infno… ¶

Removes the inferior or inferiors infno…. It is not possible to remove an inferior that is running with this command. For those, use the kill or detach command first.

To quit debugging one of the running inferiors that is not the current inferior, you can either detach from it by using the detach inferior command (allowing it to run independently), or kill it using the kill inferiors command:

detach inferior infno… ¶

Detach from the inferior or inferiors identified by GDB inferior number(s) infno…. Note that the inferior’s entry still stays on the list of inferiors shown by info inferiors, but its Description will show ‘<null>’.

kill inferiors infno… ¶

Kill the inferior or inferiors identified by GDB inferior number(s) infno…. Note that the inferior’s entry still stays on the list of inferiors shown by info inferiors, but its Description will show ‘<null>’.

After the successful completion of a command such as detach, detach inferiors, kill or kill inferiors, or after a normal process exit, the inferior is still valid and listed with info inferiors, ready to be restarted.

To be notified when inferiors are started or exit under GDB’s control use set print inferior-events:

set print inferior-events ¶

set print inferior-events on

set print inferior-events off

The set print inferior-events command allows you to enable or disable printing of messages when GDB notices that new inferiors have started or that inferiors have exited or have been detached. By default, these messages will be printed.

show print inferior-events ¶

Show whether messages will be printed when GDB detects that inferiors have started, exited or have been detached.

Many commands will work the same with multiple programs as with a single program: e.g., print myglobal will simply display the value of myglobal in the current inferior.

Occasionally, when debugging GDB itself, it may be useful to get more info about the relationship of inferiors, programs, address spaces in a debug session. You can do that with the maint info program-spaces command.

maint info program-spaces ¶

Print a list of all program spaces currently being managed by GDB.

GDB displays for each program space (in this order):

1. the program space number assigned by GDB
2. the name of the executable loaded into the program space, with e.g., the file command.
3. the name of the core file loaded into the program space, with e.g., the core-file command.

An asterisk ‘*’ preceding the GDB program space number indicates the current program space.

In addition, below each program space line, GDB prints extra information that isn’t suitable to display in tabular form. For example, the list of inferiors bound to the program space.

(gdb) maint info program-spaces
  Id   Executable        Core File
* 1    hello
  2    goodbye
        Bound inferiors: ID 1 (process 21561)

Here we can see that no inferior is running the program hello, while process 21561 is running the program goodbye. On some targets, it is possible that multiple inferiors are bound to the same program space. The most common example is that of debugging both the parent and child processes of a vfork call. For example,

(gdb) maint info program-spaces
  Id   Executable        Core File
* 1    vfork-test
        Bound inferiors: ID 2 (process 18050), ID 1 (process 18045)

Here, both inferior 2 and inferior 1 are running in the same program space as a result of inferior 1 having executed a vfork call.

• Inferior-Specific Breakpoints

(gdb) remove-inferiors 2
Inferior-specific breakpoint 3 deleted - inferior 2 has been removed.

4.10 Debugging Programs with Multiple Threads ¶

In some operating systems, such as GNU/Linux and Solaris, a single program may have more than one thread of execution. The precise semantics of threads differ from one operating system to another, but in general the threads of a single program are akin to multiple processes—except that they share one address space (that is, they can all examine and modify the same variables). On the other hand, each thread has its own registers and execution stack, and perhaps private memory.

GDB provides these facilities for debugging multi-thread programs:

• automatic notification of new threads
• ‘thread thread-id’, a command to switch among threads
• ‘info threads’, a command to inquire about existing threads
• ‘thread apply [thread-id-list | all] args’, a command to apply a command to a list of threads
• thread-specific breakpoints
• ‘set print thread-events’, which controls printing of messages on thread start and exit.
• ‘set libthread-db-search-path path’, which lets the user specify which libthread_db to use if the default choice isn’t compatible with the program.

The GDB thread debugging facility allows you to observe all threads while your program runs—but whenever GDB takes control, one thread in particular is always the focus of debugging. This thread is called the current thread. Debugging commands show program information from the perspective of the current thread.

Whenever GDB detects a new thread in your program, it displays the target system’s identification for the thread with a message in the form ‘[New systag]’, where systag is a thread identifier whose form varies depending on the particular system. For example, on GNU/Linux, you might see

[New Thread 0x41e02940 (LWP 25582)]

when GDB notices a new thread. In contrast, on other systems, the systag is simply something like ‘process 368’, with no further qualifier.

For debugging purposes, GDB associates its own thread number —always a single integer—with each thread of an inferior. This number is unique between all threads of an inferior, but not unique between threads of different inferiors.

You can refer to a given thread in an inferior using the qualified inferior-num.thread-num syntax, also known as qualified thread ID, with inferior-num being the inferior number and thread-num being the thread number of the given inferior. For example, thread 2.3 refers to thread number 3 of inferior 2. If you omit inferior-num (e.g., thread 3), then GDB infers you’re referring to a thread of the current inferior.

Until you create a second inferior, GDB does not show the inferior-num part of thread IDs, even though you can always use the full inferior-num.thread-num form to refer to threads of inferior 1, the initial inferior.

Some commands accept a space-separated thread ID list as argument. A list element can be:

1. A thread ID as shown in the first field of the ‘info threads’ display, with or without an inferior qualifier. E.g., ‘2.1’ or ‘1’.
2. A range of thread numbers, again with or without an inferior qualifier, as in inf.thr1-thr2 or thr1-thr2. E.g., ‘1.2-4’ or ‘2-4’.
3. All threads of an inferior, specified with a star wildcard, with or without an inferior qualifier, as in inf.* (e.g., ‘1.*’) or *. The former refers to all threads of the given inferior, and the latter form without an inferior qualifier refers to all threads of the current inferior.

For example, if the current inferior is 1, and inferior 7 has one thread with ID 7.1, the thread list ‘1 2-3 4.5 6.7-9 7.*’ includes threads 1 to 3 of inferior 1, thread 5 of inferior 4, threads 7 to 9 of inferior 6 and all threads of inferior 7. That is, in expanded qualified form, the same as ‘1.1 1.2 1.3 4.5 6.7 6.8 6.9 7.1’.

In addition to a per-inferior number, each thread is also assigned a unique global number, also known as global thread ID, a single integer. Unlike the thread number component of the thread ID, no two threads have the same global ID, even when you’re debugging multiple inferiors.

From GDB’s perspective, a process always has at least one thread. In other words, GDB assigns a thread number to the program’s “main thread” even if the program is not multi-threaded.

The debugger convenience variables ‘$_thread’ and ‘$_gthread’ contain, respectively, the per-inferior thread number and the global thread number of the current thread. You may find this useful in writing breakpoint conditional expressions, command scripts, and so forth. The convenience variable ‘$_inferior_thread_count’ contains the number of live threads in the current inferior. See Convenience Variables, for general information on convenience variables.

When running in non-stop mode (see Non-Stop Mode), where new threads can be created, and existing threads exit, at any time, ‘$_inferior_thread_count’ could return a different value each time it is evaluated.

If GDB detects the program is multi-threaded, it augments the usual message about stopping at a breakpoint with the ID and name of the thread that hit the breakpoint.

Thread 2 "client" hit Breakpoint 1, send_message () at client.c:68

Likewise when the program receives a signal:

Thread 1 "main" received signal SIGINT, Interrupt.

info threads [-gid] [thread-id-list] ¶

Display information about one or more threads. With no arguments displays information about all threads. You can specify the list of threads that you want to display using the thread ID list syntax (see thread ID lists).

GDB displays for each thread (in this order):

1. the per-inferior thread number assigned by GDB
2. the global thread number assigned by GDB, if the ‘-gid’ option was specified
3. the target system’s thread identifier (systag)
4. the thread’s name, if one is known. A thread can either be named by the user (see thread name, below), or, in some cases, by the program itself.
5. the current stack frame summary for that thread

An asterisk ‘*’ to the left of the GDB thread number indicates the current thread.

For example,

(gdb) info threads
  Id   Target Id             Frame
* 1    process 35 thread 13  main (argc=1, argv=0x7ffffff8)
  2    process 35 thread 23  0x34e5 in sigpause ()
  3    process 35 thread 27  0x34e5 in sigpause ()
    at threadtest.c:68

If you’re debugging multiple inferiors, GDB displays thread IDs using the qualified inferior-num.thread-num format. Otherwise, only thread-num is shown.

If you specify the ‘-gid’ option, GDB displays a column indicating each thread’s global thread ID:

(gdb) info threads
  Id   GId  Target Id             Frame
  1.1  1    process 35 thread 13  main (argc=1, argv=0x7ffffff8)
  1.2  3    process 35 thread 23  0x34e5 in sigpause ()
  1.3  4    process 35 thread 27  0x34e5 in sigpause ()
* 2.1  2    process 65 thread 1   main (argc=1, argv=0x7ffffff8)

On Solaris, you can display more information about user threads with a Solaris-specific command:

maint info sol-threads ¶

Display info on Solaris user threads.

thread thread-id ¶

Make thread ID thread-id the current thread. The command argument thread-id is the GDB thread ID, as shown in the first field of the ‘info threads’ display, with or without an inferior qualifier (e.g., ‘2.1’ or ‘1’).

GDB responds by displaying the system identifier of the thread you selected, and its current stack frame summary:

(gdb) thread 2
[Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))]
#0  some_function (ignore=0x0) at example.c:8
8	    printf ("hello\n");

As with the ‘[New …]’ message, the form of the text after ‘Switching to’ depends on your system’s conventions for identifying threads.

thread apply [thread-id-list | all [-ascending]] [flag]… command ¶

The thread apply command allows you to apply the named command to one or more threads. Specify the threads that you want affected using the thread ID list syntax (see thread ID lists), or specify all to apply to all threads. To apply a command to all threads in descending order, type thread apply all command. To apply a command to all threads in ascending order, type thread apply all -ascending command.

The flag arguments control what output to produce and how to handle errors raised when applying command to a thread. flag must start with a - directly followed by one letter in qcs. If several flags are provided, they must be given individually, such as -c -q.

By default, GDB displays some thread information before the output produced by command, and an error raised during the execution of a command will abort thread apply. The following flags can be used to fine-tune this behavior:

-c

The flag -c, which stands for ‘continue’, causes any errors in command to be displayed, and the execution of thread apply then continues.

-s

The flag -s, which stands for ‘silent’, causes any errors or empty output produced by a command to be silently ignored. That is, the execution continues, but the thread information and errors are not printed.

-q

The flag -q (‘quiet’) disables printing the thread information.

Flags -c and -s cannot be used together.

taas [option]… command ¶

Shortcut for thread apply all -s [option]… command. Applies command on all threads, ignoring errors and empty output.

The taas command accepts the same options as the thread apply all command. See thread apply all.

tfaas [option]… command ¶

Shortcut for thread apply all -s -- frame apply all -s [option]… command. Applies command on all frames of all threads, ignoring errors and empty output. Note that the flag -s is specified twice: The first -s ensures that thread apply only shows the thread information of the threads for which frame apply produces some output. The second -s is needed to ensure that frame apply shows the frame information of a frame only if the command successfully produced some output.

It can for example be used to print a local variable or a function argument without knowing the thread or frame where this variable or argument is, using:

(gdb) tfaas p some_local_var_i_do_not_remember_where_it_is

The tfaas command accepts the same options as the frame apply command. See frame apply.

thread name [name] ¶

This command assigns a name to the current thread. If no argument is given, any existing user-specified name is removed. The thread name appears in the ‘info threads’ display.

On some systems, such as GNU/Linux, GDB is able to determine the name of the thread as given by the OS. On these systems, a name specified with ‘thread name’ will override the system-give name, and removing the user-specified name will cause GDB to once again display the system-specified name.

thread find [regexp] ¶

Search for and display thread ids whose name or systag matches the supplied regular expression.

As well as being the complement to the ‘thread name’ command, this command also allows you to identify a thread by its target systag. For instance, on GNU/Linux, the target systag is the LWP id.

(gdb) thread find 26688
Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)'
(gdb) info thread 4
  Id   Target Id         Frame 
  4    Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select ()

set print thread-events ¶

set print thread-events on

set print thread-events off

The set print thread-events command allows you to enable or disable printing of messages when GDB notices that new threads have started or that threads have exited. By default, these messages will be printed if detection of these events is supported by the target. Note that these messages cannot be disabled on all targets.

show print thread-events ¶

Show whether messages will be printed when GDB detects that threads have started and exited.

See Stopping and Starting Multi-thread Programs, for more information about how GDB behaves when you stop and start programs with multiple threads.

See Setting Watchpoints, for information about watchpoints in programs with multiple threads.

set libthread-db-search-path [path] ¶

If this variable is set, path is a colon-separated list of directories GDB will use to search for libthread_db. If you omit path, ‘libthread-db-search-path’ will be reset to its default value ($sdir:$pdir on GNU/Linux and Solaris systems). Internally, the default value comes from the LIBTHREAD_DB_SEARCH_PATH macro.

On GNU/Linux and Solaris systems, GDB uses a “helper” libthread_db library to obtain information about threads in the inferior process. GDB will use ‘libthread-db-search-path’ to find libthread_db. GDB also consults first if inferior specific thread debugging library loading is enabled by ‘set auto-load libthread-db’ (see Automatically loading thread debugging library).

A special entry ‘$sdir’ for ‘libthread-db-search-path’ refers to the default system directories that are normally searched for loading shared libraries. The ‘$sdir’ entry is the only kind not needing to be enabled by ‘set auto-load libthread-db’ (see Automatically loading thread debugging library).

A special entry ‘$pdir’ for ‘libthread-db-search-path’ refers to the directory from which libpthread was loaded in the inferior process.

For any libthread_db library GDB finds in above directories, GDB attempts to initialize it with the current inferior process. If this initialization fails (which could happen because of a version mismatch between libthread_db and libpthread), GDB will unload libthread_db, and continue with the next directory. If none of libthread_db libraries initialize successfully, GDB will issue a warning and thread debugging will be disabled.

Setting libthread-db-search-path is currently implemented only on some platforms.

show libthread-db-search-path ¶

Display current libthread_db search path.

set debug libthread-db ¶

show debug libthread-db

Turns on or off display of libthread_db-related events. Use 1 to enable, 0 to disable.

set debug threads [on|off] ¶

show debug threads

When ‘on’ GDB will print additional messages when threads are created and deleted.

4.11 Debugging Forks ¶

On most systems, GDB has no special support for debugging programs which create additional processes using the fork function. When a program forks, GDB will continue to debug the parent process and the child process will run unimpeded. If you have set a breakpoint in any code which the child then executes, the child will get a SIGTRAP signal which (unless it catches the signal) will cause it to terminate.

However, if you want to debug the child process there is a workaround which isn’t too painful. Put a call to sleep in the code which the child process executes after the fork. It may be useful to sleep only if a certain environment variable is set, or a certain file exists, so that the delay need not occur when you don’t want to run GDB on the child. While the child is sleeping, use the ps program to get its process ID. Then tell GDB (a new invocation of GDB if you are also debugging the parent process) to attach to the child process (see Debugging an Already-running Process). From that point on you can debug the child process just like any other process which you attached to.

On some systems, GDB provides support for debugging programs that create additional processes using the fork or vfork functions. On GNU/Linux platforms, this feature is supported with kernel version 2.5.46 and later.

The fork debugging commands are supported in native mode and when connected to gdbserver in either target remote mode or target extended-remote mode.

By default, when a program forks, GDB will continue to debug the parent process and the child process will run unimpeded.

If you want to follow the child process instead of the parent process, use the command set follow-fork-mode.

set follow-fork-mode mode ¶

Set the debugger response to a program call of fork or vfork. A call to fork or vfork creates a new process. The mode argument can be:

parent

The original process is debugged after a fork. The child process runs unimpeded. This is the default.

child

The new process is debugged after a fork. The parent process runs unimpeded.

show follow-fork-mode ¶

Display the current debugger response to a fork or vfork call.

On Linux, if you want to debug both the parent and child processes, use the command set detach-on-fork.

set detach-on-fork mode ¶

Tells gdb whether to detach one of the processes after a fork, or retain debugger control over them both.

on

The child process (or parent process, depending on the value of follow-fork-mode) will be detached and allowed to run independently. This is the default.

off

Both processes will be held under the control of GDB. One process (child or parent, depending on the value of follow-fork-mode) is debugged as usual, while the other is held suspended.

show detach-on-fork ¶

Show whether detach-on-fork mode is on/off.

If you choose to set ‘detach-on-fork’ mode off, then GDB will retain control of all forked processes (including nested forks). You can list the forked processes under the control of GDB by using the info inferiors command, and switch from one fork to another by using the inferior command (see Debugging Multiple Inferiors Connections and Programs).

To quit debugging one of the forked processes, you can either detach from it by using the detach inferiors command (allowing it to run independently), or kill it using the kill inferiors command. See Debugging Multiple Inferiors Connections and Programs.

If you ask to debug a child process and a vfork is followed by an exec, GDB executes the new target up to the first breakpoint in the new target. If you have a breakpoint set on main in your original program, the breakpoint will also be set on the child process’s main.

On some systems, when a child process is spawned by vfork, you cannot debug the child or parent until an exec call completes.

If you issue a run command to GDB after an exec call executes, the new target restarts. To restart the parent process, use the file command with the parent executable name as its argument. By default, after an exec call executes, GDB discards the symbols of the previous executable image. You can change this behaviour with the set follow-exec-mode command.

set follow-exec-mode mode ¶

Set debugger response to a program call of exec. An exec call replaces the program image of a process.

follow-exec-mode can be:

new

GDB creates a new inferior and rebinds the process to this new inferior. The program the process was running before the exec call can be restarted afterwards by restarting the original inferior.

For example:

(gdb) info inferiors
(gdb) info inferior
  Id   Description   Executable
* 1    <null>        prog1
(gdb) run
process 12020 is executing new program: prog2
Program exited normally.
(gdb) info inferiors
  Id   Description   Executable
  1    <null>        prog1
* 2    <null>        prog2

same

GDB keeps the process bound to the same inferior. The new executable image replaces the previous executable loaded in the inferior. Restarting the inferior after the exec call, with e.g., the run command, restarts the executable the process was running after the exec call. This is the default mode.

For example:

(gdb) info inferiors
  Id   Description   Executable
* 1    <null>        prog1
(gdb) run
process 12020 is executing new program: prog2
Program exited normally.
(gdb) info inferiors
  Id   Description   Executable
* 1    <null>        prog2

follow-exec-mode is supported in native mode and target extended-remote mode.

You can use the catch command to make GDB stop whenever a fork, vfork, or exec call is made. See Setting Catchpoints.

4.12 Setting a Bookmark to Return to Later ¶

On certain operating systems⁴, GDB is able to save a snapshot of a program’s state, called a checkpoint, and come back to it later.

Returning to a checkpoint effectively undoes everything that has happened in the program since the checkpoint was saved. This includes changes in memory, registers, and even (within some limits) system state. Effectively, it is like going back in time to the moment when the checkpoint was saved.

Thus, if you’re stepping thru a program and you think you’re getting close to the point where things go wrong, you can save a checkpoint. Then, if you accidentally go too far and miss the critical statement, instead of having to restart your program from the beginning, you can just go back to the checkpoint and start again from there.

This can be especially useful if it takes a lot of time or steps to reach the point where you think the bug occurs.

To use the checkpoint/restart method of debugging:

checkpoint ¶

Save a snapshot of the debugged program’s current execution state. The checkpoint command takes no arguments, but each checkpoint is assigned a small integer id, similar to a breakpoint id.

info checkpoints ¶

List the checkpoints that have been saved in the current debugging session. For each checkpoint, the following information will be listed:

Checkpoint ID

Process ID

Code Address

Source line, or label

restart checkpoint-id ¶

Restore the program state that was saved as checkpoint number checkpoint-id. All program variables, registers, stack frames etc. will be returned to the values that they had when the checkpoint was saved. In essence, gdb will “wind back the clock” to the point in time when the checkpoint was saved.

Note that breakpoints, GDB variables, command history etc. are not affected by restoring a checkpoint. In general, a checkpoint only restores things that reside in the program being debugged, not in the debugger.

delete checkpoint checkpoint-id ¶

Delete the previously-saved checkpoint identified by checkpoint-id.

Returning to a previously saved checkpoint will restore the user state of the program being debugged, plus a significant subset of the system (OS) state, including file pointers. It won’t “un-write” data from a file, but it will rewind the file pointer to the previous location, so that the previously written data can be overwritten. For files opened in read mode, the pointer will also be restored so that the previously read data can be read again.

Of course, characters that have been sent to a printer (or other external device) cannot be “snatched back”, and characters received from eg. a serial device can be removed from internal program buffers, but they cannot be “pushed back” into the serial pipeline, ready to be received again. Similarly, the actual contents of files that have been changed cannot be restored (at this time).

However, within those constraints, you actually can “rewind” your program to a previously saved point in time, and begin debugging it again — and you can change the course of events so as to debug a different execution path this time.

Finally, there is one bit of internal program state that will be different when you return to a checkpoint — the program’s process id. Each checkpoint will have a unique process id (or pid), and each will be different from the program’s original pid. If your program has saved a local copy of its process id, this could potentially pose a problem.

• A Non-obvious Benefit of Using Checkpoints

5.1 Breakpoints, Watchpoints, and Catchpoints ¶

A breakpoint makes your program stop whenever a certain point in the program is reached. For each breakpoint, you can add conditions to control in finer detail whether your program stops. You can set breakpoints with the break command and its variants (see Setting Breakpoints), to specify the place where your program should stop by line number, function name or exact address in the program.

On some systems, you can set breakpoints in shared libraries before the executable is run.

A watchpoint is a special breakpoint that stops your program when the value of an expression changes. The expression may be a value of a variable, or it could involve values of one or more variables combined by operators, such as ‘a + b’. This is sometimes called data breakpoints. You must use a different command to set watchpoints (see Setting Watchpoints), but aside from that, you can manage a watchpoint like any other breakpoint: you enable, disable, and delete both breakpoints and watchpoints using the same commands.

You can arrange to have values from your program displayed automatically whenever GDB stops at a breakpoint. See Automatic Display.

A catchpoint is another special breakpoint that stops your program when a certain kind of event occurs, such as the throwing of a C++ exception or the loading of a library. As with watchpoints, you use a different command to set a catchpoint (see Setting Catchpoints), but aside from that, you can manage a catchpoint like any other breakpoint. (To stop when your program receives a signal, use the handle command; see Signals.)

GDB assigns a number to each breakpoint, watchpoint, or catchpoint when you create it; these numbers are successive integers starting with one. In many of the commands for controlling various features of breakpoints you use the breakpoint number to say which breakpoint you want to change. Each breakpoint may be enabled or disabled; if disabled, it has no effect on your program until you enable it again.

Some GDB commands accept a space-separated list of breakpoints on which to operate. A list element can be either a single breakpoint number, like ‘5’, or a range of such numbers, like ‘5-7’. When a breakpoint list is given to a command, all breakpoints in that list are operated on.

• Setting Breakpoints
• Setting Watchpoints
• Setting Catchpoints
• Deleting Breakpoints
• Disabling Breakpoints
• Break Conditions
• Breakpoint Command Lists
• Dynamic Printf
• How to save breakpoints to a file
• Static Probe Points
• “Cannot insert breakpoints”
• “Breakpoint address adjusted...”

(gdb) b main
Breakpoint 1 at 0x11c6: file zeoes.c, line 24.
(gdb) p $bpnum
$1 = 1

(gdb) b some_func
Breakpoint 2 at 0x1179: some_func. (3 locations)
(gdb) p $bpnum
$2 = 2
(gdb)

Thread 1 "zeoes" hit Breakpoint 2.1, some_func () at zeoes.c:8
8	  printf("some func\n");
(gdb) p $_hit_bpnum
$5 = 2
(gdb) p $_hit_locno
$6 = 1
(gdb)

Breakpoint 1, main (argc=1, argv=0x7fffffffe018) at zeoes.c:24
24	  if (argc > 1)
(gdb) p $_hit_bpnum
$3 = 1
(gdb) p $_hit_locno
$4 = 1
(gdb)

(gdb) alias lld = disable $_hit_bpnum.$_hit_locno
(gdb) alias lbd = disable $_hit_bpnum

Num     Type           Disp Enb  Address    What
1       breakpoint     keep y    <MULTIPLE>
        stop only if i==1
        breakpoint already hit 1 time
1.1                         y    0x080486a2 in void foo<int>() at t.cc:8
1.2                         y    0x080486ca in void foo<double>() at t.cc:8

(gdb) info breakpoints
Num     Type           Disp Enb Address            What
1       breakpoint     keep n   <MULTIPLE>
1.1                         y-  0x00000000000011b6 in ...
1.2                         y-  0x00000000000011c2 in ...
1.3                         n   0x00000000000011ce in ...

(gdb) watch 0x600850
Cannot watch constant value 0x600850.
(gdb) watch *(int *) 0x600850
Watchpoint 1: *(int *) 6293584

Hardware watchpoint num: expr

Expression cannot be implemented with read/access watchpoint.

Hardware watchpoint num: Could not insert watchpoint

break foo if x>0
commands
silent
printf "x is %d\n",x
cont
end

break 403
commands
silent
set x = y + 4
cont
end

Stopped; cannot insert breakpoints.
You may have requested too many hardware breakpoints and watchpoints.

warning: Breakpoint address adjusted from 0x00010414 to 0x00010410.

warning: Breakpoint 1 address previously adjusted from 0x00010414
to 0x00010410.

5.2 Continuing and Stepping ¶

Continuing means resuming program execution until your program completes normally. In contrast, stepping means executing just one more “step” of your program, where “step” may mean either one line of source code, or one machine instruction (depending on what particular command you use). Either when continuing or when stepping, your program may stop even sooner, due to a breakpoint or a signal. (If it stops due to a signal, you may want to use handle, or use ‘signal 0’ to resume execution (see Signals), or you may step into the signal’s handler (see stepping and signal handlers).)

continue [ignore-count] ¶

c [ignore-count]

fg [ignore-count]

Resume program execution, at the address where your program last stopped; any breakpoints set at that address are bypassed. The optional argument ignore-count allows you to specify a further number of times to ignore a breakpoint at this location; its effect is like that of ignore (see Break Conditions).

The argument ignore-count is meaningful only when your program stopped due to a breakpoint. At other times, the argument to continue is ignored.

The synonyms c and fg (for foreground, as the debugged program is deemed to be the foreground program) are provided purely for convenience, and have exactly the same behavior as continue.

To resume execution at a different place, you can use return (see Returning from a Function) to go back to the calling function; or jump (see Continuing at a Different Address) to go to an arbitrary location in your program.

A typical technique for using stepping is to set a breakpoint (see Breakpoints; Watchpoints; and Catchpoints) at the beginning of the function or the section of your program where a problem is believed to lie, run your program until it stops at that breakpoint, and then step through the suspect area, examining the variables that are interesting, until you see the problem happen.

step ¶

Continue running your program until control reaches a different source line, then stop it and return control to GDB. This command is abbreviated s.

Warning: If you use the step command while control is within a function that was compiled without debugging information, execution proceeds until control reaches a function that does have debugging information. Likewise, it will not step into a function which is compiled without debugging information. To step through functions without debugging information, use the stepi command, described below.

The step command only stops at the first instruction of a source line. This prevents the multiple stops that could otherwise occur in switch statements, for loops, etc. step continues to stop if a function that has debugging information is called within the line. In other words, step steps inside any functions called within the line.

Also, the step command only enters a function if there is line number information for the function. Otherwise it acts like the next command. This avoids problems when using cc -gl on MIPS machines. Previously, step entered subroutines if there was any debugging information about the routine.

step count

Continue running as in step, but do so count times. If a breakpoint is reached, or a signal not related to stepping occurs before count steps, stepping stops right away.

next [count] ¶

Continue to the next source line in the current (innermost) stack frame. This is similar to step, but function calls that appear within the line of code are executed without stopping. Execution stops when control reaches a different line of code at the original stack level that was executing when you gave the next command. This command is abbreviated n.

An argument count is a repeat count, as for step.

The next command only stops at the first instruction of a source line. This prevents multiple stops that could otherwise occur in switch statements, for loops, etc.

set step-mode ¶

set step-mode on

The set step-mode on command causes the step command to stop at the first instruction of a function which contains no debug line information rather than stepping over it.

This is useful in cases where you may be interested in inspecting the machine instructions of a function which has no symbolic info and do not want GDB to automatically skip over this function.

set step-mode off

Causes the step command to step over any functions which contains no debug information. This is the default.

show step-mode

Show whether GDB will stop in or step over functions without source line debug information.

finish ¶

Continue running until just after function in the selected stack frame returns. Print the returned value (if any). This command can be abbreviated as fin.

Contrast this with the return command (see Returning from a Function).

set print finish [on|off] ¶

show print finish

By default the finish command will show the value that is returned by the function. This can be disabled using set print finish off. When disabled, the value is still entered into the value history (see Value History), but not displayed.

until ¶

u

Continue running until a source line past the current line, in the current stack frame, is reached. This command is used to avoid single stepping through a loop more than once. It is like the next command, except that when until encounters a jump, it automatically continues execution until the program counter is greater than the address of the jump.

This means that when you reach the end of a loop after single stepping though it, until makes your program continue execution until it exits the loop. In contrast, a next command at the end of a loop simply steps back to the beginning of the loop, which forces you to step through the next iteration.

until always stops your program if it attempts to exit the current stack frame.

until may produce somewhat counterintuitive results if the order of machine code does not match the order of the source lines. For example, in the following excerpt from a debugging session, the f (frame) command shows that execution is stopped at line 206; yet when we use until, we get to line 195:

(gdb) f
#0  main (argc=4, argv=0xf7fffae8) at m4.c:206
206                 expand_input();
(gdb) until
195             for ( ; argc > 0; NEXTARG) {

This happened because, for execution efficiency, the compiler had generated code for the loop closure test at the end, rather than the start, of the loop—even though the test in a C for-loop is written before the body of the loop. The until command appeared to step back to the beginning of the loop when it advanced to this expression; however, it has not really gone to an earlier statement—not in terms of the actual machine code.

until with no argument works by means of single instruction stepping, and hence is slower than until with an argument.

until locspec

u locspec

Continue running your program until either it reaches a code location that results from resolving locspec, or the current stack frame returns. locspec is any of the forms described in Location Specifications. This form of the command uses temporary breakpoints, and hence is quicker than until without an argument. The specified location is actually reached only if it is in the current frame. This implies that until can be used to skip over recursive function invocations. For instance in the code below, if the current location is line 96, issuing until 99 will execute the program up to line 99 in the same invocation of factorial, i.e., after the inner invocations have returned.

94	int factorial (int value)
95	{
96	    if (value > 1) {
97            value *= factorial (value - 1);
98	    }
99	    return (value);
100     }

advance locspec ¶

Continue running your program until either it reaches a code location that results from resolving locspec, or the current stack frame returns. locspec is any of the forms described in Location Specifications. This command is similar to until, but advance will not skip over recursive function calls, and the target code location doesn’t have to be in the same frame as the current one.

stepi ¶

stepi arg

si

Execute one machine instruction, then stop and return to the debugger.

It is often useful to do ‘display/i $pc’ when stepping by machine instructions. This makes GDB automatically display the next instruction to be executed, each time your program stops. See Automatic Display.

An argument is a repeat count, as in step.

nexti ¶

nexti arg

ni

Execute one machine instruction, but if it is a function call, proceed until the function returns.

An argument is a repeat count, as in next.

By default, and if available, GDB makes use of target-assisted range stepping. In other words, whenever you use a stepping command (e.g., step, next), GDB tells the target to step the corresponding range of instruction addresses instead of issuing multiple single-steps. This speeds up line stepping, particularly for remote targets. Ideally, there should be no reason you would want to turn range stepping off. However, it’s possible that a bug in the debug info, a bug in the remote stub (for remote targets), or even a bug in GDB could make line stepping behave incorrectly when target-assisted range stepping is enabled. You can use the following command to turn off range stepping if necessary:

set range-stepping ¶

show range-stepping

Control whether range stepping is enabled.

If on, and the target supports it, GDB tells the target to step a range of addresses itself, instead of issuing multiple single-steps. If off, GDB always issues single-steps, even if range stepping is supported by the target. The default is on.

5.3 Skipping Over Functions and Files ¶

The program you are debugging may contain some functions which are uninteresting to debug. The skip command lets you tell GDB to skip a function, all functions in a file or a particular function in a particular file when stepping.

For example, consider the following C function:

101     int func()
102     {
103         foo(boring());
104         bar(boring());
105     }

Suppose you wish to step into the functions foo and bar, but you are not interested in stepping through boring. If you run step at line 103, you’ll enter boring(), but if you run next, you’ll step over both foo and boring!

One solution is to step into boring and use the finish command to immediately exit it. But this can become tedious if boring is called from many places.

A more flexible solution is to execute skip boring. This instructs GDB never to step into boring. Now when you execute step at line 103, you’ll step over boring and directly into foo.

Functions may be skipped by providing either a function name, linespec (see Location Specifications), regular expression that matches the function’s name, file name or a glob-style pattern that matches the file name.

On Posix systems the form of the regular expression is “Extended Regular Expressions”. See for example ‘man 7 regex’ on GNU/Linux systems. On non-Posix systems the form of the regular expression is whatever is provided by the regcomp function of the underlying system. See for example ‘man 7 glob’ on GNU/Linux systems for a description of glob-style patterns.

skip [options] ¶

The basic form of the skip command takes zero or more options that specify what to skip. The options argument is any useful combination of the following:

-file file

-fi file

Functions in file will be skipped over when stepping.

-gfile file-glob-pattern ¶

-gfi file-glob-pattern

Functions in files matching file-glob-pattern will be skipped over when stepping.

(gdb) skip -gfi utils/*.c

-function linespec

-fu linespec

Functions named by linespec or the function containing the line named by linespec will be skipped over when stepping. See Location Specifications.

-rfunction regexp ¶

-rfu regexp

Functions whose name matches regexp will be skipped over when stepping.

This form is useful for complex function names. For example, there is generally no need to step into C++ std::string constructors or destructors. Plus with C++ templates it can be hard to write out the full name of the function, and often it doesn’t matter what the template arguments are. Specifying the function to be skipped as a regular expression makes this easier.

(gdb) skip -rfu ^std::(allocator|basic_string)<.*>::~?\1 *\(

If you want to skip every templated C++ constructor and destructor in the std namespace you can do:

(gdb) skip -rfu ^std::([a-zA-z0-9_]+)<.*>::~?\1 *\(

If no options are specified, the function you’re currently debugging will be skipped.

skip function [linespec] ¶

After running this command, the function named by linespec or the function containing the line named by linespec will be skipped over when stepping. See Location Specifications.

If you do not specify linespec, the function you’re currently debugging will be skipped.

(If you have a function called file that you want to skip, use skip function file.)

skip file [filename] ¶

After running this command, any function whose source lives in filename will be skipped over when stepping.

(gdb) skip file boring.c
File boring.c will be skipped when stepping.

If you do not specify filename, functions whose source lives in the file you’re currently debugging will be skipped.

Skips can be listed, deleted, disabled, and enabled, much like breakpoints. These are the commands for managing your list of skips:

info skip [range] ¶

Print details about the specified skip(s). If range is not specified, print a table with details about all functions and files marked for skipping. info skip prints the following information about each skip:

Identifier

A number identifying this skip.

Enabled or Disabled

Enabled skips are marked with ‘y’. Disabled skips are marked with ‘n’.

Glob

If the file name is a ‘glob’ pattern this is ‘y’. Otherwise it is ‘n’.

File

The name or ‘glob’ pattern of the file to be skipped. If no file is specified this is ‘<none>’.

RE

If the function name is a ‘regular expression’ this is ‘y’. Otherwise it is ‘n’.

Function

The name or regular expression of the function to skip. If no function is specified this is ‘<none>’.

skip delete [range] ¶

Delete the specified skip(s). If range is not specified, delete all skips.

skip enable [range] ¶

Enable the specified skip(s). If range is not specified, enable all skips.

skip disable [range] ¶

Disable the specified skip(s). If range is not specified, disable all skips.

set debug skip [on|off] ¶

Set whether to print the debug output about skipping files and functions.

show debug skip ¶

Show whether the debug output about skipping files and functions is printed.

5.4 Signals ¶

A signal is an asynchronous event that can happen in a program. The operating system defines the possible kinds of signals, and gives each kind a name and a number. For example, in Unix SIGINT is the signal a program gets when you type an interrupt character (often Ctrl-c); SIGSEGV is the signal a program gets from referencing a place in memory far away from all the areas in use; SIGALRM occurs when the alarm clock timer goes off (which happens only if your program has requested an alarm).

Some signals, including SIGALRM, are a normal part of the functioning of your program. Others, such as SIGSEGV, indicate errors; these signals are fatal (they kill your program immediately) if the program has not specified in advance some other way to handle the signal. SIGINT does not indicate an error in your program, but it is normally fatal so it can carry out the purpose of the interrupt: to kill the program.

GDB has the ability to detect any occurrence of a signal in your program. You can tell GDB in advance what to do for each kind of signal.

Normally, GDB is set up to let the non-erroneous signals like SIGALRM be silently passed to your program (so as not to interfere with their role in the program’s functioning) but to stop your program immediately whenever an error signal happens. You can change these settings with the handle command.

info signals ¶

info handle

Print a table of all the kinds of signals and how GDB has been told to handle each one. You can use this to see the signal numbers of all the defined types of signals.

info signals sig

Similar, but print information only about the specified signal number.

info handle is an alias for info signals.

catch signal [signal… | ‘all’]

Set a catchpoint for the indicated signals. See Setting Catchpoints, for details about this command.

handle signal [ signal … ] [keywords…] ¶

Change the way GDB handles each signal. Each signal can be the number of a signal or its name (with or without the ‘SIG’ at the beginning); a list of signal numbers of the form ‘low-high’; or the word ‘all’, meaning all the known signals, except SIGINT and SIGTRAP, which are used by GDB. Optional argument keywords, described below, say what changes to make to all of the specified signals.