[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can alter the way GDB interacts with you by using the
set
command. For commands controlling how GDB displays
data, see Print Settings. Other settings are
described here.
22.1 Prompt 22.2 Command Editing Command editing 22.3 Command History Command history 22.4 Screen Size Screen size 22.5 Numbers 22.6 Configuring the Current ABI Configuring the current ABI 22.7 Automatically loading associated files 22.8 Optional Warnings and Messages Optional warnings and messages 22.9 Optional Messages about Internal Happenings Optional messages about internal happenings 22.10 Other Miscellaneous Settings
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GDB indicates its readiness to read a command by printing a string
called the prompt. This string is normally `(gdb)'. You
can change the prompt string with the set prompt
command. For
instance, when debugging GDB with GDB, it is useful to change
the prompt in one of the GDB sessions so that you can always tell
which one you are talking to.
Note: set prompt
does not add a space for you after the
prompt you set. This allows you to set a prompt which ends in a space
or a prompt that does not.
set prompt newprompt
show prompt
Versions of GDB that ship with Python scripting enabled have prompt extensions. The commands for interacting with these extensions are:
set extended-prompt prompt
For example:
set extended-prompt Current working directory: \w (gdb) |
Note that when an extended-prompt is set, it takes control of the prompt_hook hook. See prompt_hook, for further information.
show extended-prompt
set extended-prompt
, are replaced with the
corresponding strings each time the prompt is displayed.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GDB reads its input commands via the Readline interface. This
GNU library provides consistent behavior for programs which provide a
command line interface to the user. Advantages are GNU Emacs-style
or vi-style inline editing of commands, csh
-like history
substitution, and a storage and recall of command history across
debugging sessions.
You may control the behavior of command line editing in GDB with the
command set
.
set editing
set editing on
set editing off
show editing
See section 32. Command Line Editing,
for more details about the Readline
interface. Users unfamiliar with GNU Emacs or vi
are
encouraged to read that chapter.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GDB can keep track of the commands you type during your debugging sessions, so that you can be certain of precisely what happened. Use these commands to manage the GDB command history facility.
GDB uses the GNU History library, a part of the Readline package, to provide the history facility. See section 33. Using History Interactively, for the detailed description of the History library.
To issue a command to GDB without affecting certain aspects of the state which is seen by users, prefix it with `server ' (see section 28.2 The Server Prefix). This means that this command will not affect the command history, nor will it affect GDB's notion of which command to repeat if RET is pressed on a line by itself.
The server prefix does not affect the recording of values into the value
history; to print a value without recording it into the value history,
use the output
command instead of the print
command.
Here is the description of GDB commands related to command history.
set history filename fname
GDBHISTFILE
, or to
`./.gdb_history' (`./_gdb_history' on MS-DOS) if this variable
is not set.
set history save
set history save on
set history filename
command. By default, this option is disabled.
set history save off
set history size size
set history size unlimited
HISTSIZE
, or to 256 if this variable is not set. If size
is unlimited
, the number of commands GDB keeps in the
history list is unlimited.
History expansion assigns special meaning to the character !. See section 33.1.1 Event Designators, for more details.
Since ! is also the logical not operator in C, history expansion
is off by default. If you decide to enable history expansion with the
set history expansion on
command, you may sometimes need to
follow ! (when it is used as logical not, in an expression) with
a space or a tab to prevent it from being expanded. The readline
history facilities do not attempt substitution on the strings
!= and !(, even when history expansion is enabled.
The commands to control history expansion are:
set history expansion on
set history expansion
set history expansion off
show history
show history filename
show history save
show history size
show history expansion
show history
by itself displays all four states.
show commands
show commands n
show commands +
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Certain commands to GDB may produce large amounts of information output to the screen. To help you read all of it, GDB pauses and asks you for input at the end of each page of output. Type RET when you want to continue the output, or q to discard the remaining output. Also, the screen width setting determines when to wrap lines of output. Depending on what is being printed, GDB tries to break the line at a readable place, rather than simply letting it overflow onto the following line.
Normally GDB knows the size of the screen from the terminal
driver software. For example, on Unix GDB uses the termcap data base
together with the value of the TERM
environment variable and the
stty rows
and stty cols
settings. If this is not correct,
you can override it with the set height
and set
width
commands:
set height lpp
set height unlimited
show height
set width cpl
set width unlimited
show width
set
commands specify a screen height of lpp lines and
a screen width of cpl characters. The associated show
commands display the current settings.
If you specify a height of either unlimited
or zero lines,
GDB does not pause during output no matter how long the
output is. This is useful if output is to a file or to an editor
buffer.
Likewise, you can specify `set width unlimited' or `set width 0' to prevent GDB from wrapping its output.
set pagination on
set pagination off
set height unlimited
. Note that
running GDB with the `--batch' option (see section -batch) also automatically disables pagination.
show pagination
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can always enter numbers in octal, decimal, or hexadecimal in GDB by the usual conventions: octal numbers begin with `0', decimal numbers end with `.', and hexadecimal numbers begin with `0x'. Numbers that neither begin with `0' or `0x', nor end with a `.' are, by default, entered in base 10; likewise, the default display for numbers--when no particular format is specified--is base 10. You can change the default base for both input and output with the commands described below.
set input-radix base
set input-radix 012 set input-radix 10. set input-radix 0xa |
sets the input base to decimal. On the other hand, `set input-radix 10' leaves the input radix unchanged, no matter what it was, since `10', being without any leading or trailing signs of its base, is interpreted in the current radix. Thus, if the current radix is 16, `10' is interpreted in hex, i.e. as 16 decimal, which doesn't change the radix.
set output-radix base
show input-radix
show output-radix
set radix [base]
show radix
set radix
sets the radix of input and output to
the same base; without an argument, it resets the radix back to its
default value of 10.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GDB can determine the ABI (Application Binary Interface) of your application automatically. However, sometimes you need to override its conclusions. Use these commands to manage GDB's view of the current ABI.
One GDB configuration can debug binaries for multiple operating
system targets, either via remote debugging or native emulation.
GDB will autodetect the OS ABI (Operating System ABI) in use,
but you can override its conclusion using the set osabi
command.
One example where this is useful is in debugging of binaries which use
an alternate C library (e.g. UCLIBC for GNU/Linux) which does
not have the same identifying marks that the standard C library for your
platform provides.
When GDB is debugging the AArch64 architecture, it provides a
"Newlib" OS ABI. This is useful for handling setjmp
and
longjmp
when debugging binaries that use the NEWLIB C library.
The "Newlib" OS ABI can be selected by set osabi Newlib
.
show osabi
set osabi
set osabi abi
Generally, the way that an argument of type float
is passed to a
function depends on whether the function is prototyped. For a prototyped
(i.e. ANSI/ISO style) function, float
arguments are passed unchanged,
according to the architecture's convention for float
. For unprototyped
(i.e. K&R style) functions, float
arguments are first promoted to type
double
and then passed.
Unfortunately, some forms of debug information do not reliably indicate whether a function is prototyped. If GDB calls a function that is not marked as prototyped, it consults set coerce-float-to-double.
set coerce-float-to-double
set coerce-float-to-double on
float
will be promoted to double
when passed
to an unprototyped function. This is the default setting.
set coerce-float-to-double off
float
will be passed directly to unprototyped
functions.
show coerce-float-to-double
float
to double
.
GDB needs to know the ABI used for your program's C++
objects. The correct C++ ABI depends on which C++ compiler was
used to build your application. GDB only fully supports
programs with a single C++ ABI; if your program contains code using
multiple C++ ABI's or if GDB can not identify your
program's ABI correctly, you can tell GDB which ABI to use.
Currently supported ABI's include "gnu-v2", for g++
versions
before 3.0, "gnu-v3", for g++
versions 3.0 and later, and
"hpaCC" for the HP ANSI C++ compiler. Other C++ compilers may
use the "gnu-v2" or "gnu-v3" ABI's as well. The default setting is
"auto".
show cp-abi
set cp-abi
set cp-abi abi
set cp-abi auto
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GDB sometimes reads files with commands and settings automatically, without being explicitly told so by the user. We call this feature auto-loading. While auto-loading is useful for automatically adapting GDB to the needs of your project, it can sometimes produce unexpected results or introduce security risks (e.g., if the file comes from untrusted sources).
22.7.1 Automatically loading init file in the current directory `set/show/info auto-load local-gdbinit' 22.7.2 Automatically loading thread debugging library `set/show/info auto-load libthread-db'
22.7.3 Security restriction for auto-loading `set/show/info auto-load safe-path' 22.7.4 Displaying files tried for auto-load `set/show debug auto-load'
There are various kinds of files GDB can automatically load. In addition to these files, GDB supports auto-loading code written in various extension languages. See section 23.3 Auto-loading extensions.
Note that loading of these associated files (including the local `.gdbinit'
file) requires accordingly configured auto-load safe-path
(see section 22.7.3 Security restriction for auto-loading).
For these reasons, GDB includes commands and options to let you control when to auto-load files and which files should be auto-loaded.
set auto-load off
$ gdb -iex "set auto-load off" untrusted-executable corefile |
Be aware that system init file (see section C.6 System-wide configuration and settings)
and init files from your home directory (see Home Directory Init File)
still get read (as they come from generally trusted directories).
To prevent GDB from auto-loading even those init files, use the
`-nx' option (see section 2.1.2 Choosing Modes), in addition to
set auto-load no
.
show auto-load
(gdb) show auto-load gdb-scripts: Auto-loading of canned sequences of commands scripts is on. libthread-db: Auto-loading of inferior specific libthread_db is on. local-gdbinit: Auto-loading of .gdbinit script from current directory is on. python-scripts: Auto-loading of Python scripts is on. safe-path: List of directories from which it is safe to auto-load files is $debugdir:$datadir/auto-load. scripts-directory: List of directories from which to load auto-loaded scripts is $debugdir:$datadir/auto-load. |
info auto-load
(gdb) info auto-load gdb-scripts: Loaded Script Yes /home/user/gdb/gdb-gdb.gdb libthread-db: No auto-loaded libthread-db. local-gdbinit: Local .gdbinit file "/home/user/gdb/.gdbinit" has been loaded. python-scripts: Loaded Script Yes /home/user/gdb/gdb-gdb.py |
These are GDB control commands for the auto-loading:
See set auto-load off. | Disable auto-loading globally. |
See show auto-load. | Show setting of all kinds of files. |
See info auto-load. | Show state of all kinds of files. |
See set auto-load gdb-scripts. | Control for GDB command scripts. |
See show auto-load gdb-scripts. | Show setting of GDB command scripts. |
See info auto-load gdb-scripts. | Show state of GDB command scripts. |
See set auto-load python-scripts. | Control for GDB Python scripts. |
See show auto-load python-scripts. | Show setting of GDB Python scripts. |
See info auto-load python-scripts. | Show state of GDB Python scripts. |
See set auto-load scripts-directory. | Control for GDB auto-loaded scripts location. |
See show auto-load scripts-directory. | Show GDB auto-loaded scripts location. |
See set auto-load local-gdbinit. | Control for init file in the current directory. |
See show auto-load local-gdbinit. | Show setting of init file in the current directory. |
See info auto-load local-gdbinit. | Show state of init file in the current directory. |
See set auto-load libthread-db. | Control for thread debugging library. |
See show auto-load libthread-db. | Show setting of thread debugging library. |
See info auto-load libthread-db. | Show state of thread debugging library. |
See set auto-load safe-path. | Control directories trusted for automatic loading. |
See show auto-load safe-path. | Show directories trusted for automatic loading. |
See add-auto-load-safe-path. | Add directory trusted for automatic loading. |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
By default, GDB reads and executes the canned sequences of commands from init file (if any) in the current working directory, see Init File in the Current Directory during Startup.
Note that loading of this local `.gdbinit' file also requires accordingly
configured auto-load safe-path
(see section 22.7.3 Security restriction for auto-loading).
set auto-load local-gdbinit [on|off]
show auto-load local-gdbinit
info auto-load local-gdbinit
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This feature is currently present only on GNU/Linux native hosts.
GDB reads in some cases thread debugging library from places specific to the inferior (see set libthread-db-search-path).
The special `libthread-db-search-path' entry `$sdir' is processed without checking this `set auto-load libthread-db' switch as system libraries have to be trusted in general. In all other cases of `libthread-db-search-path' entries GDB checks first if `set auto-load libthread-db' is enabled before trying to open such thread debugging library.
Note that loading of this debugging library also requires accordingly configured
auto-load safe-path
(see section 22.7.3 Security restriction for auto-loading).
set auto-load libthread-db [on|off]
show auto-load libthread-db
info auto-load libthread-db
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
As the files of inferior can come from untrusted source (such as submitted by an application user) GDB does not always load any files automatically. GDB provides the `set auto-load safe-path' setting to list directories trusted for loading files not explicitly requested by user. Each directory can also be a shell wildcard pattern.
If the path is not set properly you will see a warning and the file will not get loaded:
$ ./gdb -q ./gdb Reading symbols from /home/user/gdb/gdb...done. warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been declined by your `auto-load safe-path' set to "$debugdir:$datadir/auto-load". warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been declined by your `auto-load safe-path' set to "$debugdir:$datadir/auto-load". |
To instruct GDB to go ahead and use the init files anyway, invoke GDB like this:
$ gdb -q -iex "set auto-load safe-path /home/user/gdb" ./gdb |
The list of trusted directories is controlled by the following commands:
set auto-load safe-path [directories]
FNM_PATHNAME
for system function fnmatch
(see section `Wildcard Matching' in GNU C Library Reference Manual).
If you omit directories, `auto-load safe-path' will be reset to
its default value as specified during GDB compilation.
The list of directories uses path separator (`:' on GNU and Unix
systems, `;' on MS-Windows and MS-DOS) to separate directories, similarly
to the PATH
environment variable.
show auto-load safe-path
add-auto-load-safe-path
This variable defaults to what --with-auto-load-dir
has been configured
to (see with-auto-load-dir). `$debugdir' and `$datadir'
substitution applies the same as for set auto-load scripts-directory.
The default set auto-load safe-path
value can be also overriden by
GDB configuration option `--with-auto-load-safe-path'.
Setting this variable to `/' disables this security protection, corresponding GDB configuration option is `--without-auto-load-safe-path'. This variable is supposed to be set to the system directories writable by the system superuser only. Users can add their source directories in init files in their home directories (see Home Directory Init File). See also deprecated init file in the current directory (see Init File in the Current Directory during Startup).
To force GDB to load the files it declined to load in the previous example, you could use one of the following ways:
On the other hand you can also explicitly forbid automatic files loading which also suppresses any such warning messages:
This setting applies to the file names as entered by user. If no entry matches GDB tries as a last resort to also resolve all the file names into their canonical form (typically resolving symbolic links) and compare the entries again. GDB already canonicalizes most of the filenames on its own before starting the comparison so a canonical form of directories is recommended to be entered.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
For better visibility of all the file locations where you can place scripts to be auto-loaded with inferior -- or to protect yourself against accidental execution of untrusted scripts -- GDB provides a feature for printing all the files attempted to be loaded. Both existing and non-existing files may be printed.
For example the list of directories from which it is safe to auto-load files (see section 22.7.3 Security restriction for auto-loading) applies also to canonicalized filenames which may not be too obvious while setting it up.
(gdb) set debug auto-load on (gdb) file ~/src/t/true auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb" for objfile "/tmp/true". auto-load: Updating directories of "/usr:/opt". auto-load: Using directory "/usr". auto-load: Using directory "/opt". warning: File "/tmp/true-gdb.gdb" auto-loading has been declined by your `auto-load safe-path' set to "/usr:/opt". |
set debug auto-load [on|off]
show debug auto-load
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
By default, GDB is silent about its inner workings. If you are
running on a slow machine, you may want to use the set verbose
command. This makes GDB tell you when it does a lengthy
internal operation, so you will not think it has crashed.
Currently, the messages controlled by set verbose
are those
which announce that the symbol table for a source file is being read;
see symbol-file
in Commands to Specify Files.
set verbose on
set verbose off
show verbose
set verbose
is on or off.
By default, if GDB encounters bugs in the symbol table of an object file, it is silent; but if you are debugging a compiler, you may find this information useful (see section Errors Reading Symbol Files).
set complaints limit
show complaints
By default, GDB is cautious, and asks what sometimes seems to be a lot of stupid questions to confirm certain commands. For example, if you try to run a program which is already running:
(gdb) run The program being debugged has been started already. Start it from the beginning? (y or n) |
If you are willing to unflinchingly face the consequences of your own commands, you can disable this "feature":
set confirm off
set confirm on
show confirm
If you need to debug user-defined commands or sourced files you may find it useful to enable command tracing. In this mode each command will be printed as it is executed, prefixed with one or more `+' symbols, the quantity denoting the call depth of each command.
set trace-commands on
set trace-commands off
show trace-commands
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GDB has commands that enable optional debugging messages from various GDB subsystems; normally these commands are of interest to GDB maintainers, or when reporting a bug. This section documents those commands.
set exec-done-display
show exec-done-display
set debug aarch64
show debug aarch64
set debug arch
show debug arch
set debug aix-solib
show debug aix-thread
set debug aix-thread
show debug aix-thread
set debug check-physname
show debug check-physname
set debug coff-pe-read
show debug coff-pe-read
set debug dwarf2-die
show debug dwarf2-die
set debug dwarf2-read
show debug dwarf2-read
set debug displaced
show debug displaced
set debug event
show debug event
set debug expression
show debug expression
set debug frame
show debug frame
set debug gnu-nat
show debug gnu-nat
set debug infrun
show debug infrun
set debug jit
show debug jit
set debug lin-lwp
show debug lin-lwp
set debug mach-o
show debug mach-o
set debug notification
show debug notification
set debug observer
show debug observer
set debug overload
show debug overload
set debug parser
yydebug
variable in the expression
parser. See section `Tracing Your Parser' in Bison, for
details. The default is off.
show debug parser
set debug remote
show debug remote
set debug serial
show debug serial
set debug solib-frv
show debug solib-frv
set debug symfile
show debug symfile
set debug symtab-create
show debug symtab-create
set debug target
run
command.
show debug target
set debug timestamp
show debug timestamp
set debug unwind
show debug unwind
set debugvarobj
show debugvarobj
set debug xml
show debug xml
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
set interactive-mode
on
, forces GDB to assume that GDB was started
in a terminal. In practice, this means that GDB should wait
for the user to answer queries generated by commands entered at
the command prompt. If off
, forces GDB to operate
in the opposite mode, and it uses the default answers to all queries.
If auto
(the default), GDB tries to determine whether
its standard input is a terminal, and works in interactive-mode if it
is, non-interactively otherwise.
In the vast majority of cases, the debugger should be able to guess correctly which mode should be used. But this setting can be useful in certain specific cases, such as running a MinGW GDB inside a cygwin window.
show interactive-mode
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |