\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988-2017 Free Software Foundation, Inc.
+@c Copyright (C) 1988-2019 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@copying
@c man begin COPYRIGHT
-Copyright @copyright{} 1988-2017 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2019 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2017 Free Software Foundation, Inc.
+Copyright (C) 1988-2019 Free Software Foundation, Inc.
This edition of the GDB manual is dedicated to the memory of Fred
Fish. Fred was a long-standing contributor to GDB and to Free
Computer Laboratory under DARPA/AFRL contract FA8750-10-C-0237
("CTSRD"), as part of the DARPA CRASH research programme.
+Initial support for the FreeBSD/riscv target and native configuration
+was developed by SRI International and the University of Cambridge
+Computer Laboratory (Department of Computer Science and Technology)
+under DARPA contract HR0011-18-C-0016 ("ECATS"), as part of the DARPA
+SSITH research programme.
+
+The original port to the OpenRISC 1000 is believed to be due to
+Alessandro Forin and Per Bothner. More recent ports have been the work
+of Jeremy Bennett, Franck Jullien, Stefan Wallentowitz and
+Stafford Horne.
+
@node Sample Session
@chapter A Sample @value{GDBN} Session
@value{GDBP} @var{program} @var{core}
@end smallexample
-You can, instead, specify a process ID as a second argument, if you want
-to debug a running process:
+You can, instead, specify a process ID as a second argument or use option
+@code{-p}, if you want to debug a running process:
@smallexample
@value{GDBP} @var{program} 1234
+@value{GDBP} -p 1234
@end smallexample
@noindent
-would attach @value{GDBN} to process @code{1234} (unless you also have a file
-named @file{1234}; @value{GDBN} does check for a core file first).
+would attach @value{GDBN} to process @code{1234}. With option @option{-p} you
+can omit the @var{program} filename.
Taking advantage of the second command-line argument requires a fairly
complete operating system; when you use @value{GDBN} as a remote
the default, which is to read it incrementally as it is needed.
This makes startup slower, but makes future operations faster.
+@item --readnever
+@anchor{--readnever}
+@cindex @code{--readnever}, command-line option
+Do not read each symbol file's symbolic debug information. This makes
+startup faster but at the expense of not being able to perform
+symbolic debugging. DWARF unwind information is also not read,
+meaning backtraces may become incomplete or inaccurate. One use of
+this is when a user simply wants to do the following sequence: attach,
+dump core, detach. Loading the debugging information in this case is
+an unnecessary cause of delay.
@end table
@node Mode Options
configure option (@pxref{System-wide configuration}).
It is loaded first when @value{GDBN} starts, before command line options
have been processed.
+@item @file{system.gdbinit.d}
+This is the system-wide init directory.
+Its location is specified with the @code{--with-system-gdbinit-dir}
+configure option (@pxref{System-wide configuration}).
+Files in this directory are loaded in alphabetical order immediately after
+system.gdbinit (if enabled) when @value{GDBN} starts, before command line
+options have been processed. Files need to have a recognized scripting
+language extension (@file{.py}/@file{.scm}) or be named with a @file{.gdb}
+extension to be interpreted as regular @value{GDBN} commands. @value{GDBN}
+will not recurse into any subdirectories of this directory.
@item @file{~/.gdbinit}
This is the init file in your home directory.
It is loaded next, after @file{system.gdbinit}, and before
communicate with @value{GDBN} using it as a back end.
@xref{Interpreters, , Command Interpreters}.
-@samp{--interpreter=mi} (or @samp{--interpreter=mi2}) causes
-@value{GDBN} to use the @dfn{@sc{gdb/mi} interface} (@pxref{GDB/MI, ,
-The @sc{gdb/mi} Interface}) included since @value{GDBN} version 6.0. The
-previous @sc{gdb/mi} interface, included in @value{GDBN} version 5.3 and
-selected with @samp{--interpreter=mi1}, is deprecated. Earlier
-@sc{gdb/mi} interfaces are no longer supported.
+@samp{--interpreter=mi} (or @samp{--interpreter=mi3}) causes
+@value{GDBN} to use the @dfn{@sc{gdb/mi} interface} version 3 (@pxref{GDB/MI, ,
+The @sc{gdb/mi} Interface}) included since @value{GDBN} version 9.1. @sc{gdb/mi}
+version 2 (@code{mi2}), included in @value{GDBN} 6.0 and version 1 (@code{mi1}),
+included in @value{GDBN} 5.3, are also available. Earlier @sc{gdb/mi}
+interfaces are no longer supported.
@item -write
@cindex @code{--write}
@cindex init file
Reads the system-wide @dfn{init file} (if @option{--with-system-gdbinit} was
used when building @value{GDBN}; @pxref{System-wide configuration,
- ,System-wide configuration and settings}) and executes all the commands in
-that file.
+ ,System-wide configuration and settings}) and the files in the system-wide
+gdbinit directory (if @option{--with-system-gdbinit-dir} was used) and executes
+all the commands in those files. The files need to be named with a @file{.gdb}
+extension to be interpreted as @value{GDBN} commands, or they can be written
+in a supported scripting language with an appropriate file extension.
@anchor{Home Directory Init File}
@item
arguments. This is equivalent to @samp{shell make @var{make-args}}.
@end table
+@table @code
+@kindex pipe
+@kindex |
+@cindex send the output of a gdb command to a shell command
+@anchor{pipe}
+@item pipe [@var{command}] | @var{shell_command}
+@itemx | [@var{command}] | @var{shell_command}
+@itemx pipe -d @var{delim} @var{command} @var{delim} @var{shell_command}
+@itemx | -d @var{delim} @var{command} @var{delim} @var{shell_command}
+Executes @var{command} and sends its output to @var{shell_command}.
+Note that no space is needed around @code{|}.
+If no @var{command} is provided, the last command executed is repeated.
+
+In case the @var{command} contains a @code{|}, the option @code{-d @var{delim}}
+can be used to specify an alternate delimiter string @var{delim} that separates
+the @var{command} from the @var{shell_command}.
+
+Example:
+@smallexample
+@group
+(gdb) p var
+$1 = @{
+ black = 144,
+ red = 233,
+ green = 377,
+ blue = 610,
+ white = 987
+@}
+@end group
+@group
+(gdb) pipe p var|wc
+ 7 19 80
+(gdb) |p var|wc -l
+7
+@end group
+@group
+(gdb) p /x var
+$4 = @{
+ black = 0x90,
+ red = 0xe9,
+ green = 0x179,
+ blue = 0x262,
+ white = 0x3db
+@}
+(gdb) ||grep red
+ red => 0xe9,
+@end group
+@group
+(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)
+@end group
+@end smallexample
+@end table
+
+The convenience variables @code{$_shell_exitcode} and @code{$_shell_exitsignal}
+can be used to examine the exit status of the last shell command launched
+by @code{shell}, @code{make}, @code{pipe} and @code{|}.
+@xref{Convenience Vars,, Convenience Variables}.
+
@node Logging Output
@section Logging Output
@cindex logging @value{GDBN} output
@item set logging redirect [on|off]
By default, @value{GDBN} output will go to both the terminal and the logfile.
Set @code{redirect} if you want output to go only to the log file.
+@item set logging debugredirect [on|off]
+By default, @value{GDBN} debug output will go to both the terminal and the logfile.
+Set @code{debugredirect} if you want debug output to go only to the log file.
@kindex show logging
@item show logging
Show the current values of the logging settings.
@end table
+You can also redirect the output of a @value{GDBN} command to a
+shell command. @xref{pipe}.
@node Commands
@chapter @value{GDBN} Commands
@menu
* Command Syntax:: How to give commands to @value{GDBN}
+* Command Settings:: How to change default behavior of commands
* Completion:: Command completion
+* Command Options:: Command options
* Help:: How to ask @value{GDBN} for help
@end menu
then fetches the next line relative to the current line from the history
for editing.
+
+@node Command Settings
+@section Command Settings
+@cindex default behavior of commands, changing
+@cindex default settings, changing
+
+Many commands change their behavior according to command-specific
+variables or settings. These settings can be changed with the
+@code{set} subcommands. For example, the @code{print} command
+(@pxref{Data, ,Examining Data}) prints arrays differently depending on
+settings changeable with the commands @code{set print elements
+NUMBER-OF-ELEMENTS} and @code{set print array-indexes}, among others.
+
+You can change these settings to your preference in the gdbinit files
+loaded at @value{GDBN} startup. @xref{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:
+@smallexample
+(@value{GDBN}) set print elements 10
+(@value{GDBN}) print some_array
+$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@}
+@end smallexample
+
+The above @code{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 @code{some_array}, then you
+must restore the limit back to 200, with @code{set print elements
+200}.
+
+Some commands allow overriding settings with command options. For
+example, the @code{print} command supports a number of options that
+allow overriding relevant global print settings as set by @code{set
+print} subcommands. @xref{print options}. The example above could be
+rewritten as:
+@smallexample
+(@value{GDBN}) print -elements 10 -- some_array
+$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@}
+@end smallexample
+
+Alternatively, you can use the @code{with} command to change a setting
+temporarily, for the duration of a command invocation.
+
+@table @code
+@kindex with command
+@kindex w @r{(@code{with})}
+@cindex settings
+@cindex temporarily change settings
+@item with @var{setting} [@var{value}] [-- @var{command}]
+@itemx w @var{setting} [@var{value}] [-- @var{command}]
+Temporarily set @var{setting} to @var{value} for the duration of
+@var{command}.
+
+@var{setting} is any setting you can change with the @code{set}
+subcommands. @var{value} is the value to assign to @code{setting}
+while running @code{command}.
+
+If no @var{command} is provided, the last command executed is
+repeated.
+
+If a @var{command} is provided, it must be preceded by a double dash
+(@code{--}) separator. This is required because some settings accept
+free-form arguments, such as expressions or filenames.
+
+For example, the command
+@smallexample
+(@value{GDBN}) with print array on -- print some_array
+@end smallexample
+@noindent
+is equivalent to the following 3 commands:
+@smallexample
+(@value{GDBN}) set print array on
+(@value{GDBN}) print some_array
+(@value{GDBN}) set print array off
+@end smallexample
+
+The @code{with} command is particularly useful when you want to
+override a setting while running user-defined commands, or commands
+defined in Python or Guile. @xref{Extending GDB,, Extending GDB}.
+
+@smallexample
+(@value{GDBN}) with print pretty on -- my_complex_command
+@end smallexample
+
+To change several settings for the same command, you can nest
+@code{with} commands. For example, @code{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.
+
+@end table
+
@node Completion
@section Command Completion
@value{GDBN} 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 @value{GDBN}
-commands, @value{GDBN} subcommands, and the names of symbols in your program.
+commands, @value{GDBN} subcommands, command options, and the names of symbols
+in your program.
Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest
of a word. If there is only one possibility, @value{GDBN} fills in the
situation, you may enclose words in @code{'} (single quote marks) in
@value{GDBN} commands.
-The most likely situation where you might need this is in typing the
-name of a C@t{++} function. This is because C@t{++} allows function
-overloading (multiple definitions of the same function, distinguished
-by argument type). For example, when you want to set a breakpoint you
-may need to distinguish whether you mean the version of @code{name}
-that takes an @code{int} parameter, @code{name(int)}, or the version
-that takes a @code{float} parameter, @code{name(float)}. To use the
-word-completion facilities in this situation, type a single quote
+A likely situation where you might need this is in typing an
+expression that involves a C@t{++} symbol name with template
+parameters. This is because when completing expressions, GDB treats
+the @samp{<} character as word delimiter, assuming that it's the
+less-than comparison operator (@pxref{C Operators, , C and C@t{++}
+Operators}).
+
+For example, when you want to call a C@t{++} template function
+interactively using the @code{print} or @code{call} commands, you may
+need to distinguish whether you mean the version of @code{name} that
+was specialized for @code{int}, @code{name<int>()}, or the version
+that was specialized for @code{float}, @code{name<float>()}. To use
+the word-completion facilities in this situation, type a single quote
@code{'} at the beginning of the function name. This alerts
@value{GDBN} that it may need to consider more information than usual
when you press @key{TAB} or @kbd{M-?} to request word completion:
@smallexample
-(@value{GDBP}) b 'bubble( @kbd{M-?}
-bubble(double,double) bubble(int,int)
-(@value{GDBP}) b 'bubble(
+(@value{GDBP}) p 'func< @kbd{M-?}
+func<int>() func<float>()
+(@value{GDBP}) p 'func<
@end smallexample
-In some cases, @value{GDBN} can tell that completing a name requires using
-quotes. When this happens, @value{GDBN} inserts the quote for you (while
-completing as much as it can) if you do not type the quote in the first
-place:
+When setting breakpoints however (@pxref{Specify Location}), you don't
+usually need to type a quote before the function name, because
+@value{GDBN} understands that you want to set a breakpoint on a
+function:
@smallexample
-(@value{GDBP}) b bub @key{TAB}
-@exdent @value{GDBN} alters your input line to the following, and rings a bell:
-(@value{GDBP}) b 'bubble(
+(@value{GDBP}) b func< @kbd{M-?}
+func<int>() func<float>()
+(@value{GDBP}) b func<
@end smallexample
-@noindent
-In general, @value{GDBN} can tell that a quote is needed (and inserts it) if
-you have not yet started typing the argument list when you ask for
-completion on an overloaded symbol.
+This is true even in the case of typing the name of C@t{++} 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 @code{name}
+that takes an @code{int} parameter, @code{name(int)}, or the version
+that takes a @code{float} parameter, @code{name(float)}.
+
+@smallexample
+(@value{GDBP}) b bubble( @kbd{M-?}
+bubble(int) bubble(double)
+(@value{GDBP}) b bubble(dou @kbd{M-?}
+bubble(double)
+@end smallexample
+
+See @ref{quoting names} for a description of other scenarios that
+require quoting.
For more information about overloaded functions, see @ref{C Plus Plus
Expressions, ,C@t{++} Expressions}. You can use the command @code{set
@}
@end smallexample
+@node Command Options
+@section Command options
+
+@cindex command options
+Some commands accept options starting with a leading dash. For
+example, @code{print -pretty}. Similarly to command names, you can
+abbreviate a @value{GDBN} option to the first few letters of the
+option name, if that abbreviation is unambiguous, and you can also use
+the @key{TAB} key to get @value{GDBN} 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).
+
+@cindex command options, raw input
+Some commands take raw input as argument. For example, the print
+command processes arbitrary expressions in any of the languages
+supported by @value{GDBN}. 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.@: @code{print -r} (short for @code{print
+-raw} or printing negative @code{r}?), if you specify any command
+option, then you must use a double-dash (@code{--}) delimiter to
+indicate the end of options.
+
+@cindex command options, boolean
+
+Some options are described as accepting an argument which can be
+either @code{on} or @code{off}. These are known as @dfn{boolean
+options}. Similarly to boolean settings commands---@code{on} and
+@code{off} are the typical values, but any of @code{1}, @code{yes} and
+@code{enable} can also be used as ``true'' value, and any of @code{0},
+@code{no} and @code{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:
+
+@smallexample
+(@value{GDBP}) print -object on -pretty off -element unlimited -- *myptr
+(@value{GDBP}) p -o -p 0 -e u -- *myptr
+@end smallexample
+
+You can discover the set of options some command accepts by completing
+on @code{-} after the command name. For example:
+
+@smallexample
+(@value{GDBP}) print -@key{TAB}@key{TAB}
+-address -max-depth -repeats -vtbl
+-array -null-stop -static-members
+-array-indexes -object -symbol
+-elements -pretty -union
+@end smallexample
+
+Completion will in some cases guide you with a suggestion of what kind
+of argument an option expects. For example:
+
+@smallexample
+(@value{GDBP}) print -elements @key{TAB}@key{TAB}
+NUMBER unlimited
+@end smallexample
+
+Here, the option expects a number (e.g., @code{100}), not literal
+@code{NUMBER}. Such metasyntactical arguments are always presented in
+uppercase.
+
+(For more on using the @code{print} command, see @ref{Data, ,Examining
+Data}.)
@node Help
@section Getting Help
short paragraph on how to use that command.
@kindex apropos
-@item apropos @var{args}
+@item apropos [-v] @var{regexp}
The @code{apropos} command searches through all of the @value{GDBN}
commands, and their documentation, for the regular expression specified in
-@var{args}. It prints out all matches found. For example:
+@var{args}. It prints out all matches found. The optional flag @samp{-v},
+which stands for @samp{verbose}, indicates to output the full documentation
+of the matching commands and highlight the parts of the documentation
+matching @var{regexp}. For example:
@smallexample
apropos alias
results in:
@smallexample
-@c @group
+@group
alias -- Define a new command that is an alias of an existing command
aliases -- Aliases of other commands
d -- Delete some breakpoints or auto-display expressions
del -- Delete some breakpoints or auto-display expressions
delete -- Delete some breakpoints or auto-display expressions
-@c @end group
+@end group
+@end smallexample
+
+@noindent
+while
+
+@smallexample
+apropos -v cut.*thread apply
+@end smallexample
+
+@noindent
+results in the below output, where @samp{cut for 'thread apply}
+is highlighted if styling is enabled.
+
+@smallexample
+@group
+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'
+@end group
@end smallexample
@kindex complete
the DWARF debugging format, and specify the option @option{-g3}.
@xref{Debugging Options,,Options for Debugging Your Program or GCC,
-gcc.info, Using the @sc{gnu} Compiler Collection (GCC)}, for more
+gcc, Using the @sc{gnu} Compiler Collection (GCC)}, for more
information on @value{NGCC} options affecting debug information.
You will have the best debugging experience if you use the latest
your program. @xref{Environment, ,Your Program's Environment}.
@item The @emph{working directory.}
-Your program inherits its working directory from @value{GDBN}. You can set
-the @value{GDBN} working directory with the @code{cd} command in @value{GDBN}.
-@xref{Working Directory, ,Your Program's Working Directory}.
+You can set your program's working directory with the command
+@kbd{set cwd}. If you do not set any working directory with this
+command, your program will inherit @value{GDBN}'s working directory if
+native debugging, or the remote server's working directory if remote
+debugging. @xref{Working Directory, ,Your Program's Working
+Directory}.
@item The @emph{standard input and output.}
Your program normally uses the same device for standard input and
@samp{start} or @samp{run}.
It is sometimes necessary to debug the program during elaboration. In
-these cases, using the @code{start} command would stop the execution of
-your program too late, as the program would have already completed the
-elaboration phase. Under these circumstances, insert breakpoints in your
-elaboration code before running your program.
+these cases, using the @code{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 @code{starti} command.
+
+@kindex starti
+@item starti
+@cindex run to first instruction
+The @samp{starti} command does the equivalent of setting a temporary
+breakpoint at the first instruction of a program's execution and then
+invoking the @samp{run} command. For programs containing an
+elaboration phase, the @code{starti} command will stop execution at
+the start of the elaboration phase.
@anchor{set exec-wrapper}
@kindex set exec-wrapper
@sc{djgpp}, Cygwin, MS Windows, and QNX Neutrino.
@kindex set startup-with-shell
+@anchor{set startup-with-shell}
@item set startup-with-shell
@itemx set startup-with-shell on
@itemx set startup-with-shell off
-@itemx show set startup-with-shell
+@itemx show startup-with-shell
On Unix systems, by default, if a shell is available on your target,
@value{GDBN}) uses it to start your program. Arguments of the
@code{run} command are passed to the shell, which does variable
your program. You can abbreviate @code{environment} as @code{env}.
@kindex set environment
+@anchor{set environment}
@item set environment @var{varname} @r{[}=@var{value}@r{]}
Set environment variable @var{varname} to @var{value}. The value
changes for your program (and the shell @value{GDBN} uses to launch
wrapper instead of using @code{set environment}. @xref{set
exec-wrapper}, for an example doing just that.
+Environment variables that are set by the user are also transmitted to
+@command{gdbserver} to be used when starting the remote inferior.
+@pxref{QEnvironmentHexEncoded}.
+
@kindex unset environment
+@anchor{unset environment}
@item unset environment @var{varname}
Remove variable @var{varname} from the environment to be passed to your
program. This is different from @samp{set env @var{varname} =};
@code{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
+@command{gdbserver} when starting the remote inferior.
+@pxref{QEnvironmentUnset}.
@end table
@emph{Warning:} On Unix systems, @value{GDBN} runs your program using
@section Your Program's Working Directory
@cindex working directory (of your program)
-Each time you start your program with @code{run}, it inherits its
-working directory from the current working directory of @value{GDBN}.
-The @value{GDBN} working directory is initially whatever it inherited
-from its parent process (typically the shell), but you can specify a new
-working directory in @value{GDBN} with the @code{cd} command.
-
-The @value{GDBN} working directory also serves as a default for the commands
-that specify files for @value{GDBN} to operate on. @xref{Files, ,Commands to
-Specify Files}.
+Each time you start your program with @code{run}, the inferior will be
+initialized with the current working directory specified by the
+@kbd{set cwd} command. If no directory has been specified by this
+command, then the inferior will inherit @value{GDBN}'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.
+
+@table @code
+@kindex set cwd
+@cindex change inferior's working directory
+@anchor{set cwd command}
+@item set cwd @r{[}@var{directory}@r{]}
+Set the inferior's working directory to @var{directory}, which will be
+@code{glob}-expanded in order to resolve tildes (@file{~}). If no
+argument has been specified, the command clears the setting and resets
+it to an empty state. This setting has no effect on @value{GDBN}'s
+working directory, and it only takes effect the next time you start
+the inferior. The @file{~} in @var{directory} is a short for the
+@dfn{home directory}, usually pointed to by the @env{HOME} environment
+variable. On MS-Windows, if @env{HOME} is not defined, @value{GDBN}
+uses the concatenation of @env{HOMEDRIVE} and @env{HOMEPATH} as
+fallback.
+
+You can also change @value{GDBN}'s current working directory by using
+the @code{cd} command.
+@xref{cd command}.
+
+@kindex show cwd
+@cindex show inferior's working directory
+@item show cwd
+Show the inferior's working directory. If no directory has been
+specified by @kbd{set cwd}, then the default inferior's working
+directory is the same as @value{GDBN}'s working directory.
-@table @code
@kindex cd
-@cindex change working directory
+@cindex change @value{GDBN}'s working directory
+@anchor{cd command}
@item cd @r{[}@var{directory}@r{]}
Set the @value{GDBN} working directory to @var{directory}. If not
given, @var{directory} uses @file{'~'}.
+The @value{GDBN} working directory serves as a default for the
+commands that specify files for @value{GDBN} to operate on.
+@xref{Files, ,Commands to Specify Files}.
+@xref{set cwd command}.
+
@kindex pwd
@item pwd
Print the @value{GDBN} 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 @value{GDBN} is
-configured with the @file{/proc} support, you can use the @code{info
-proc} command (@pxref{SVR4 Process Information}) to find out the
+during its run). If you work on a system where @value{GDBN} supports
+the @code{info proc} command (@pxref{Process Information}), you can
+use the @code{info proc} command to find out the
current working directory of the debuggee.
@node Input/Output
inferiors}}:
@table @code
-@kindex info inferiors
+@kindex info inferiors [ @var{id}@dots{} ]
@item info inferiors
Print a list of all inferiors currently being managed by @value{GDBN}.
+By default all inferiors are printed, but the argument @var{id}@dots{}
+-- a space separated list of inferior numbers -- can be used to limit
+the display to just the requested inferiors.
@value{GDBN} displays for each inferior (in this order):
@item automatic notification of new threads
@item @samp{thread @var{thread-id}}, a command to switch among threads
@item @samp{info threads}, a command to inquire about existing threads
-@item @samp{thread apply [@var{thread-id-list}] [@var{all}] @var{args}},
+@item @samp{thread apply [@var{thread-id-list} | all] @var{args}},
a command to apply a command to a list of threads
@item thread-specific breakpoints
@item @samp{set print thread-events}, which controls printing of
@samp{Switching to} depends on your system's conventions for identifying
threads.
+@anchor{thread apply all}
@kindex thread apply
@cindex apply command to several threads
-@item thread apply [@var{thread-id-list} | all [-ascending]] @var{command}
+@item thread apply [@var{thread-id-list} | all [-ascending]] [@var{flag}]@dots{} @var{command}
The @code{thread apply} command allows you to apply the named
@var{command} to one or more threads. Specify the threads that you
want affected using the thread ID list syntax (@pxref{thread ID
@var{command}}. To apply a command to all threads in ascending order,
type @kbd{thread apply all -ascending @var{command}}.
+The @var{flag} arguments control what output to produce and how to handle
+errors raised when applying @var{command} to a thread. @var{flag}
+must start with a @code{-} directly followed by one letter in
+@code{qcs}. If several flags are provided, they must be given
+individually, such as @code{-c -q}.
+
+By default, @value{GDBN} displays some thread information before the
+output produced by @var{command}, and an error raised during the
+execution of a @var{command} will abort @code{thread apply}. The
+following flags can be used to fine-tune this behavior:
+
+@table @code
+@item -c
+The flag @code{-c}, which stands for @samp{continue}, causes any
+errors in @var{command} to be displayed, and the execution of
+@code{thread apply} then continues.
+@item -s
+The flag @code{-s}, which stands for @samp{silent}, causes any errors
+or empty output produced by a @var{command} to be silently ignored.
+That is, the execution continues, but the thread information and errors
+are not printed.
+@item -q
+The flag @code{-q} (@samp{quiet}) disables printing the thread
+information.
+@end table
+
+Flags @code{-c} and @code{-s} cannot be used together.
+
+@kindex taas
+@cindex apply command to all threads (ignoring errors and empty output)
+@item taas [@var{option}]@dots{} @var{command}
+Shortcut for @code{thread apply all -s [@var{option}]@dots{} @var{command}}.
+Applies @var{command} on all threads, ignoring errors and empty output.
+
+The @code{taas} command accepts the same options as the @code{thread
+apply all} command. @xref{thread apply all}.
+
+@kindex tfaas
+@cindex apply a command to all frames of all threads (ignoring errors and empty output)
+@item tfaas [@var{option}]@dots{} @var{command}
+Shortcut for @code{thread apply all -s -- frame apply all -s [@var{option}]@dots{} @var{command}}.
+Applies @var{command} on all frames of all threads, ignoring errors
+and empty output. Note that the flag @code{-s} is specified twice:
+The first @code{-s} ensures that @code{thread apply} only shows the thread
+information of the threads for which @code{frame apply} produces
+some output. The second @code{-s} is needed to ensure that @code{frame
+apply} shows the frame information of a frame only if the
+@var{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:
+@smallexample
+(@value{GDBP}) tfaas p some_local_var_i_do_not_remember_where_it_is
+@end smallexample
+
+The @code{tfaas} command accepts the same options as the @code{frame
+apply} command. @xref{frame apply}.
@kindex thread name
@cindex name a thread
enable it again.
@cindex breakpoint ranges
+@cindex breakpoint lists
@cindex ranges of breakpoints
-Some @value{GDBN} commands accept a range of breakpoints on which to
-operate. A breakpoint range is either a single breakpoint number, like
-@samp{5}, or two such numbers, in increasing order, separated by a
-hyphen, like @samp{5-7}. When a breakpoint range is given to a command,
-all breakpoints in that range are operated on.
+@cindex lists of breakpoints
+Some @value{GDBN} commands accept a space-separated list of breakpoints
+on which to operate. A list element can be either a single breakpoint number,
+like @samp{5}, or a range of such numbers, like @samp{5-7}.
+When a breakpoint list is given to a command, all breakpoints in that list
+are operated on.
@menu
* Set Breaks:: Setting breakpoints
the @code{break} command. You can delete them, disable them, or make
them conditional the same way as any other breakpoint.
+In programs using different languages, @value{GDBN} chooses the syntax
+to print the list of all breakpoints it sets according to the
+@samp{set language} value: using @samp{set language auto}
+(see @ref{Automatically, ,Set Language Automatically}) means to use the
+language of the breakpoint's function, other values mean to use
+the manually specified language (see @ref{Manually, ,Set Language Manually}).
+
The syntax of the regular expression is the standard one used with tools
like @file{grep}. Note that this is different from the syntax used by
shells, so for instance @code{foo*} matches all functions that include
@kindex info breakpoints
@cindex @code{$_} and @code{info breakpoints}
-@item info breakpoints @r{[}@var{n}@dots{}@r{]}
-@itemx info break @r{[}@var{n}@dots{}@r{]}
+@item info breakpoints @r{[}@var{list}@dots{}@r{]}
+@itemx info break @r{[}@var{list}@dots{}@r{]}
Print a table of all breakpoints, watchpoints, and catchpoints set and
not deleted. Optional argument @var{n} means print information only
about the specified breakpoint(s) (or watchpoint(s) or catchpoint(s)).
1.2 y 0x080486ca in void foo<double>() at t.cc:8
@end smallexample
-Each location can be individually enabled or disabled by passing
+You cannot delete the individual locations from a breakpoint. However,
+each location can be individually enabled or disabled by passing
@var{breakpoint-number}.@var{location-number} as argument to the
-@code{enable} and @code{disable} commands. Note that you cannot
-delete the individual locations from the list, you can only delete the
-entire list of locations that belong to their parent breakpoint (with
-the @kbd{delete @var{num}} command, where @var{num} is the number of
-the parent breakpoint, 1 in the above example). Disabling or enabling
-the parent breakpoint (@pxref{Disabling}) affects all of the locations
-that belong to that breakpoint.
+@code{enable} and @code{disable} commands. It's also possible to
+@code{enable} and @code{disable} a range of @var{location-number}
+locations using a @var{breakpoint-number} and two @var{location-number}s,
+in increasing order, separated by a hyphen, like
+@kbd{@var{breakpoint-number}.@var{location-number1}-@var{location-number2}},
+in which case @value{GDBN} acts on all the locations in the range (inclusive).
+Disabling or enabling the parent breakpoint (@pxref{Disabling}) affects
+all of the locations that belong to that breakpoint.
@cindex pending breakpoints
It's quite common to have a breakpoint inside a shared library.
breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware
breakpoints.
-You can control this automatic behaviour with the following commands::
+You can control this automatic behaviour with the following commands:
@kindex set breakpoint auto-hw
@kindex show breakpoint auto-hw
Set a watchpoint that will break when @var{expr} is either read from
or written into by the program.
-@kindex info watchpoints @r{[}@var{n}@dots{}@r{]}
-@item info watchpoints @r{[}@var{n}@dots{}@r{]}
+@kindex info watchpoints @r{[}@var{list}@dots{}@r{]}
+@item info watchpoints @r{[}@var{list}@dots{}@r{]}
This command prints a list of watchpoints, using the same format as
@code{info break} (@pxref{Set Breaks}).
@end table
You cannot install an exception handler interactively.
@end itemize
-@item exception
+@item exception @r{[}@var{name}@r{]}
@kindex catch exception
@cindex Ada exception catching
@cindex catch Ada exceptions
the command to use to catch such exceptions is @kbd{catch exception
Pck.Constraint_Error}.
+@vindex $_ada_exception@r{, convenience variable}
+The convenience variable @code{$_ada_exception} holds the address of
+the exception being thrown. This can be useful when setting a
+condition for such a catchpoint.
+
@item exception unhandled
@kindex catch exception unhandled
-An exception that was raised but is not handled by the program.
+An exception that was raised but is not handled by the program. The
+convenience variable @code{$_ada_exception} is set as for @code{catch
+exception}.
+
+@item handlers @r{[}@var{name}@r{]}
+@kindex catch handlers
+@cindex Ada exception handlers catching
+@cindex catch Ada exceptions when handled
+An Ada exception being handled. If an exception name is
+specified at the end of the command
+ (eg @kbd{catch handlers Program_Error}), the debugger will stop
+only when this specific exception is handled.
+Otherwise, the debugger stops execution when any Ada exception is handled.
+
+When inserting a handlers catchpoint on a user-defined
+exception whose name is identical to one of the exceptions
+defined by the language, the fully qualified name must be used
+as the exception name. Otherwise, @value{GDBN} will assume that it
+should stop on the pre-defined exception rather than the
+user-defined one. For instance, assuming an exception called
+ @code{Constraint_Error} is defined in package @code{Pck}, then the
+command to use to catch such exceptions handling is
+@kbd{catch handlers Pck.Constraint_Error}.
+
+The convenience variable @code{$_ada_exception} is set as for
+@code{catch exception}.
@item assert
@kindex catch assert
-A failed Ada assertion.
+A failed Ada assertion. Note that the convenience variable
+@code{$_ada_exception} is @emph{not} set by this catchpoint.
@item exec
@kindex catch exec
@cindex break on fork/exec
A call to @code{exec}.
+@anchor{catch syscall}
@item syscall
@itemx syscall @r{[}@var{name} @r{|} @var{number} @r{|} @r{group:}@var{groupname} @r{|} @r{g:}@var{groupname}@r{]} @dots{}
@kindex catch syscall
@kindex catch vfork
A call to @code{vfork}.
-@item load @r{[}regexp@r{]}
-@itemx unload @r{[}regexp@r{]}
+@item load @r{[}@var{regexp}@r{]}
+@itemx unload @r{[}@var{regexp}@r{]}
@kindex catch load
@kindex catch unload
The loading or unloading of a shared library. If @var{regexp} is
@cindex delete breakpoints
@kindex delete
@kindex d @r{(@code{delete})}
-@item delete @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
+@item delete @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]}
Delete the breakpoints, watchpoints, or catchpoints of the breakpoint
-ranges specified as arguments. If no argument is specified, delete all
+list specified as argument. If no argument is specified, delete all
breakpoints (@value{GDBN} asks confirmation, unless you have @code{set
confirm off}). You can abbreviate this command as @code{d}.
@end table
@table @code
@kindex disable
@kindex dis @r{(@code{disable})}
-@item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
+@item disable @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]}
Disable the specified breakpoints---or all breakpoints, if none are
listed. A disabled breakpoint has no effect but is not forgotten. All
options such as ignore-counts, conditions and commands are remembered in
@code{disable} as @code{dis}.
@kindex enable
-@item enable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
+@item enable @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]}
Enable the specified breakpoints (or all defined breakpoints). They
become effective once again in stopping your program.
-@item enable @r{[}breakpoints@r{]} once @var{range}@dots{}
+@item enable @r{[}breakpoints@r{]} once @var{list}@dots{}
Enable the specified breakpoints temporarily. @value{GDBN} disables any
of these breakpoints immediately after stopping your program.
-@item enable @r{[}breakpoints@r{]} count @var{count} @var{range}@dots{}
+@item enable @r{[}breakpoints@r{]} count @var{count} @var{list}@dots{}
Enable the specified breakpoints temporarily. @value{GDBN} records
@var{count} with each of the specified breakpoints, and decrements a
breakpoint's count when it is hit. When any count reaches 0,
count (@pxref{Conditions, ,Break Conditions}), that will be
decremented to 0 before @var{count} is affected.
-@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{}
+@item enable @r{[}breakpoints@r{]} delete @var{list}@dots{}
Enable the specified breakpoints to work once, then die. @value{GDBN}
deletes any of these breakpoints as soon as your program stops there.
Breakpoints set by the @code{tbreak} command start out in this state.
@table @code
@kindex commands
@kindex end@r{ (breakpoint commands)}
-@item commands @r{[}@var{range}@dots{}@r{]}
+@item commands @r{[}@var{list}@dots{}@r{]}
@itemx @dots{} @var{command-list} @dots{}
@itemx end
Specify a list of commands for the given breakpoints. The commands
print commands, simply define normal breakpoints with
explicitly-supplied command lists.)
+@table @code
@item gdb
@kindex dprintf-style gdb
Handle the output using the @value{GDBN} @code{printf} command.
Have the remote debugging agent (such as @code{gdbserver}) handle
the output itself. This style is only available for agents that
support running commands on the target.
+@end table
@item set dprintf-function @var{function}
Set the function to call if the dprintf style is @code{call}. By
Contrast this with the @code{return} command (@pxref{Returning,
,Returning from a Function}).
+@kindex set print finish
+@kindex show print finish
+@item set print finish @r{[}on|off@r{]}
+@itemx show print finish
+By default the @code{finish} command will show the value that is
+returned by the function. This can be disabled using @code{set print
+finish off}. When disabled, the value is still entered into the value
+history (@pxref{Value History}), but not displayed.
+
@kindex until
@kindex u @r{(@code{until})}
@cindex run until specified location
Disable the specified skip(s). If @var{range} is not specified, disable all
skips.
+@kindex set debug skip
+@item set debug skip @r{[}on|off@r{]}
+Set whether to print the debug output about skipping files and functions.
+
+@kindex show debug skip
+@item show debug skip
+Show whether the debug output about skipping files and functions is printed.
+
@end table
@node Signals
If the target doesn't support async mode, @value{GDBN} issues an error
message if you attempt to use the background execution commands.
+@cindex @code{&}, background execution of commands
To specify background execution, add a @code{&} to the command. For example,
the background form of the @code{continue} command is @code{continue&}, or
just @code{c&}. The execution commands that accept background execution
consistant state, but @value{GDBN} accepts whatever it is given.
}.
+On some platforms, @value{GDBN} has built-in support for reverse
+execution, activated with the @code{record} or @code{record btrace}
+commands. @xref{Process Record and Replay}. Some remote targets,
+typically full system emulators, support reverse execution directly
+without requiring any special command.
+
If you are debugging in a target environment that supports
reverse execution, @value{GDBN} provides the following commands.
previous instruction; otherwise, it will work in record mode, if the
platform supports reverse execution, or stop if not.
+Currently, process record and replay is supported on ARM, Aarch64,
+Moxie, PowerPC, PowerPC64, S/390, and x86 (i386/amd64) running
+GNU/Linux. Process record and replay can be used both when native
+debugging, and when remote debugging via @code{gdbserver}.
+
For architecture environments that support process record and replay,
@value{GDBN} provides the following commands:
execution.
@item btrace @var{format}
-Hardware-supported instruction recording. This method does not record
-data. Further, the data is collected in a ring buffer so old data will
-be overwritten when the buffer is full. It allows limited reverse
-execution. Variables and registers are not available during reverse
-execution. In remote debugging, recording continues on disconnect.
-Recorded data can be inspected after reconnecting. The recording may
-be stopped using @code{record stop}.
+Hardware-supported instruction recording, supported on Intel
+processors. This method does not record data. Further, the data is
+collected in a ring buffer so old data will be overwritten when the
+buffer is full. It allows limited reverse execution. Variables and
+registers are not available during reverse execution. In remote
+debugging, recording continues on disconnect. Recorded data can be
+inspected after reconnecting. The recording may be stopped using
+@code{record stop}.
The recording format can be specified as parameter. Without a parameter
the command chooses the recording format. The following recording
to the live target and not necessarily to the current replay
position.
+@item set record btrace cpu @var{identifier}
+Set the processor to be used for enabling workarounds for processor
+errata when decoding the trace.
+
+Processor errata are defects in processor operation, caused by its
+design or manufacture. They can cause a trace not to match the
+specification. This, in turn, may cause trace decode to fail.
+@value{GDBN} can detect erroneous trace packets and correct them, thus
+avoiding the decoding failures. These corrections are known as
+@dfn{errata workarounds}, and are enabled based on the processor on
+which the trace was recorded.
+
+By default, @value{GDBN} attempts to detect the processor
+automatically, and apply the necessary workarounds for it. However,
+you may need to specify the processor if @value{GDBN} does not yet
+support it. This command allows you to do that, and also allows to
+disable the workarounds.
+
+The argument @var{identifier} identifies the @sc{cpu} and is of the
+form: @code{@var{vendor}:@var{procesor identifier}}. In addition,
+there are two special identifiers, @code{none} and @code{auto}
+(default).
+
+The following vendor identifiers and corresponding processor
+identifiers are currently supported:
+
+@multitable @columnfractions .1 .9
+
+@item @code{intel}
+@tab @var{family}/@var{model}[/@var{stepping}]
+
+@end multitable
+
+On GNU/Linux systems, the processor @var{family}, @var{model}, and
+@var{stepping} can be obtained from @code{/proc/cpuinfo}.
+
+If @var{identifier} is @code{auto}, enable errata workarounds for the
+processor on which the trace was recorded. If @var{identifier} is
+@code{none}, errata workarounds are disabled.
+
+For example, when using an old @value{GDBN} on a new system, decode
+may fail because @value{GDBN} does not support the new processor. It
+often suffices to specify an older processor that @value{GDBN}
+supports.
+
+@smallexample
+(gdb) info record
+Active record target: record-btrace
+Recording format: Intel Processor Trace.
+Buffer size: 16kB.
+Failed to configure the Intel Processor Trace decoder: unknown cpu.
+(gdb) set record btrace cpu intel:6/158
+(gdb) info record
+Active record target: record-btrace
+Recording format: Intel Processor Trace.
+Buffer size: 16kB.
+Recorded 84872 instructions in 3189 functions (0 gaps) for thread 1 (...).
+@end smallexample
+
@kindex show record btrace
@item show record btrace replay-memory-access
Show the current setting of @code{replay-memory-access}.
+@item show record btrace cpu
+Show the processor to be used for enabling trace decode errata
+workarounds.
+
@kindex set record btrace bts
@item set record btrace bts buffer-size @var{size}
@itemx set record btrace bts buffer-size unlimited
* Backtrace:: Backtraces
* Selection:: Selecting a frame
* Frame Info:: Information on a frame
+* Frame Apply:: Applying a command to several frames
* Frame Filter Management:: Managing frame filters
@end menu
in a register called the @dfn{frame pointer register}
(@pxref{Registers, $fp}) while execution is going on in that frame.
+@cindex frame level
@cindex frame number
-@value{GDBN} assigns numbers to all existing stack frames, starting with
-zero for the innermost frame, one for the frame that called it,
-and so on upward. These numbers do not really exist in your program;
-they are assigned by @value{GDBN} to give you a way of designating stack
-frames in @value{GDBN} commands.
+@value{GDBN} labels each existing stack frame with a @dfn{level}, a
+number that is zero for the innermost frame, one for the frame that
+called it, and so on upward. These level numbers give you a way of
+designating stack frames in @value{GDBN} commands. The terms
+@dfn{frame number} and @dfn{frame level} can be used interchangeably to
+describe this number.
@c The -fomit-frame-pointer below perennially causes hbox overflow
@c underflow problems.
stack.
@anchor{backtrace-command}
-@table @code
@kindex backtrace
@kindex bt @r{(@code{backtrace})}
-@item backtrace
-@itemx bt
-Print a backtrace of the entire stack: one line per frame for all
-frames in the stack.
-
-You can stop the backtrace at any time by typing the system interrupt
-character, normally @kbd{Ctrl-c}.
-
-@item backtrace @var{n}
-@itemx bt @var{n}
-Similar, but print only the innermost @var{n} frames.
-
-@item backtrace -@var{n}
-@itemx bt -@var{n}
-Similar, but print only the outermost @var{n} frames.
-
-@item backtrace full
-@itemx bt full
-@itemx bt full @var{n}
-@itemx bt full -@var{n}
-Print the values of the local variables also. As described above,
-@var{n} specifies the number of frames to print.
-
-@item backtrace no-filters
-@itemx bt no-filters
-@itemx bt no-filters @var{n}
-@itemx bt no-filters -@var{n}
-@itemx bt no-filters full
-@itemx bt no-filters full @var{n}
-@itemx bt no-filters full -@var{n}
+To print a backtrace of the entire stack, use the @code{backtrace}
+command, or its alias @code{bt}. This command will print one line per
+frame for frames in the stack. By default, all stack frames are
+printed. You can stop the backtrace at any time by typing the system
+interrupt character, normally @kbd{Ctrl-c}.
+
+@table @code
+@item backtrace [@var{option}]@dots{} [@var{qualifier}]@dots{} [@var{count}]
+@itemx bt [@var{option}]@dots{} [@var{qualifier}]@dots{} [@var{count}]
+Print the backtrace of the entire stack.
+
+The optional @var{count} can be one of the following:
+
+@table @code
+@item @var{n}
+@itemx @var{n}
+Print only the innermost @var{n} frames, where @var{n} is a positive
+number.
+
+@item -@var{n}
+@itemx -@var{n}
+Print only the outermost @var{n} frames, where @var{n} is a positive
+number.
+@end table
+
+Options:
+
+@table @code
+@item -full
+Print the values of the local variables also. This can be combined
+with the optional @var{count} to limit the number of frames shown.
+
+@item -no-filters
Do not run Python frame filters on this backtrace. @xref{Frame
Filter API}, for more information. Additionally use @ref{disable
frame-filter all} to turn off all frame filters. This is only
relevant when @value{GDBN} has been configured with @code{Python}
support.
+
+@item -hide
+A Python frame filter might decide to ``elide'' some frames. Normally
+such elided frames are still printed, but they are indented relative
+to the filtered frames that cause them to be elided. The @code{-hide}
+option causes elided frames to not be printed at all.
+@end table
+
+The @code{backtrace} command also supports a number of options that
+allow overriding relevant global print settings as set by @code{set
+backtrace} and @code{set print} subcommands:
+
+@table @code
+@item -past-main [@code{on}|@code{off}]
+Set whether backtraces should continue past @code{main}. Related setting:
+@ref{set backtrace past-main}.
+
+@item -past-entry [@code{on}|@code{off}]
+Set whether backtraces should continue past the entry point of a program.
+Related setting: @ref{set backtrace past-entry}.
+
+@item -entry-values @code{no}|@code{only}|@code{preferred}|@code{if-needed}|@code{both}|@code{compact}|@code{default}
+Set printing of function arguments at function entry.
+Related setting: @ref{set print entry-values}.
+
+@item -frame-arguments @code{all}|@code{scalars}|@code{none}
+Set printing of non-scalar frame arguments.
+Related setting: @ref{set print frame-arguments}.
+
+@item -raw-frame-arguments [@code{on}|@code{off}]
+Set whether to print frame arguments in raw form.
+Related setting: @ref{set print raw-frame-arguments}.
+
+@item -frame-info @code{auto}|@code{source-line}|@code{location}|@code{source-and-location}|@code{location-and-address}|@code{short-location}
+Set printing of frame information.
+Related setting: @ref{set print frame-info}.
+@end table
+
+The optional @var{qualifier} is maintained for backward compatibility.
+It can be one of the following:
+
+@table @code
+@item full
+Equivalent to the @code{-full} option.
+
+@item no-filters
+Equivalent to the @code{-no-filters} option.
+
+@item hide
+Equivalent to the @code{-hide} option.
+@end table
+
@end table
@kindex where
only if it is a scalar (integer, pointer, enumeration, etc). See command
@kbd{set print frame-arguments} in @ref{Print Settings} for more details
on how to configure the way function parameter values are printed.
+The command @kbd{set print frame-info} (@pxref{Print Settings}) controls
+what frame information is printed.
@cindex optimized out, in backtrace
@cindex function call arguments, optimized out
@table @code
@item set backtrace past-main
@itemx set backtrace past-main on
+@anchor{set backtrace past-main}
@kindex set backtrace
Backtraces will continue past the user entry point.
@item set backtrace past-entry
@itemx set backtrace past-entry on
+@anchor{set backtrace past-entry}
Backtraces will continue past the internal entry point of an application.
This entry point is encoded by the linker when the application is built,
and is likely before the user entry point @code{main} (or equivalent) is called.
@item set backtrace limit @var{n}
@itemx set backtrace limit 0
@itemx set backtrace limit unlimited
+@anchor{set backtrace limit}
@cindex backtrace limit
Limit the backtrace to @var{n} levels. A value of @code{unlimited}
or zero means unlimited levels.
@table @code
@kindex frame@r{, selecting}
@kindex f @r{(@code{frame})}
-@item frame @var{n}
-@itemx f @var{n}
-Select frame number @var{n}. Recall that frame zero is the innermost
+@item frame @r{[} @var{frame-selection-spec} @r{]}
+@item f @r{[} @var{frame-selection-spec} @r{]}
+The @command{frame} command allows different stack frames to be
+selected. The @var{frame-selection-spec} can be any of the following:
+
+@table @code
+@kindex frame level
+@item @var{num}
+@item level @var{num}
+Select frame level @var{num}. Recall that frame zero is the innermost
(currently executing) frame, frame one is the frame that called the
-innermost one, and so on. The highest-numbered frame is the one for
-@code{main}.
+innermost one, and so on. The highest level frame is usually the one
+for @code{main}.
-@item frame @var{stack-addr} [ @var{pc-addr} ]
-@itemx f @var{stack-addr} [ @var{pc-addr} ]
-Select the frame at address @var{stack-addr}. This is useful mainly if the
-chaining of stack frames has been damaged by a bug, making it
-impossible for @value{GDBN} to assign numbers properly to all frames. In
-addition, this can be useful when your program has multiple stacks and
-switches between them. The optional @var{pc-addr} can also be given to
-specify the value of PC for the stack frame.
+As this is the most common method of navigating the frame stack, the
+string @command{level} can be omitted. For example, the following two
+commands are equivalent:
+
+@smallexample
+(@value{GDBP}) frame 3
+(@value{GDBP}) frame level 3
+@end smallexample
+
+@kindex frame address
+@item address @var{stack-address}
+Select the frame with stack address @var{stack-address}. The
+@var{stack-address} for a frame can be seen in the output of
+@command{info frame}, for example:
+
+@smallexample
+(gdb) info frame
+Stack level 1, frame at 0x7fffffffda30:
+ rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5
+ tail call frame, caller of frame at 0x7fffffffda30
+ source language c++.
+ Arglist at unknown address.
+ Locals at unknown address, Previous frame's sp is 0x7fffffffda30
+@end smallexample
+
+The @var{stack-address} for this frame is @code{0x7fffffffda30} as
+indicated by the line:
+
+@smallexample
+Stack level 1, frame at 0x7fffffffda30:
+@end smallexample
+
+@kindex frame function
+@item function @var{function-name}
+Select the stack frame for function @var{function-name}. If there are
+multiple stack frames for function @var{function-name} then the inner
+most stack frame is selected.
+
+@kindex frame view
+@item view @var{stack-address} @r{[} @var{pc-addr} @r{]}
+View a frame that is not part of @value{GDBN}'s backtrace. The frame
+viewed has stack address @var{stack-addr}, and optionally, a program
+counter address of @var{pc-addr}.
+
+This is useful mainly if the chaining of stack frames has been
+damaged by a bug, making it impossible for @value{GDBN} to assign
+numbers properly to all frames. In addition, this can be useful
+when your program has multiple stacks and switches between them.
+
+When viewing a frame outside the current backtrace using
+@command{frame view} then you can always return to the original
+stack using one of the previous stack frame selection instructions,
+for example @command{frame level 0}.
+
+@end table
@kindex up
@item up @var{n}
@table @code
@kindex select-frame
-@item select-frame
+@item select-frame @r{[} @var{frame-selection-spec} @r{]}
The @code{select-frame} command is a variant of @code{frame} that does
not display the new frame after selecting it. This command is
intended primarily for use in @value{GDBN} command scripts, where the
-output might be unnecessary and distracting.
+output might be unnecessary and distracting. The
+@var{frame-selection-spec} is as for the @command{frame} command
+described in @ref{Selection, ,Selecting a Frame}.
@kindex down-silently
@kindex up-silently
something has gone wrong that has made the stack format fail to fit
the usual conventions.
-@item info frame @var{addr}
-@itemx info f @var{addr}
-Print a verbose description of the frame at address @var{addr}, without
-selecting that frame. The selected frame remains unchanged by this
-command. This requires the same kind of address (more than one for some
-architectures) that you specify in the @code{frame} command.
-@xref{Selection, ,Selecting a Frame}.
+@item info frame @r{[} @var{frame-selection-spec} @r{]}
+@itemx info f @r{[} @var{frame-selection-spec} @r{]}
+Print a verbose description of the frame selected by
+@var{frame-selection-spec}. The @var{frame-selection-spec} is the
+same as for the @command{frame} command (@pxref{Selection, ,Selecting
+a Frame}). The selected frame remains unchanged by this command.
@kindex info args
-@item info args
+@item info args [-q]
Print the arguments of the selected frame, each on a separate line.
-@item info locals
+The optional flag @samp{-q}, which stands for @samp{quiet}, disables
+printing header information and messages explaining why no argument
+have been printed.
+
+@item info args [-q] [-t @var{type_regexp}] [@var{regexp}]
+Like @kbd{info args}, but only print the arguments selected
+with the provided regexp(s).
+
+If @var{regexp} is provided, print only the arguments whose names
+match the regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, print only the arguments whose
+types, as printed by the @code{whatis} command, match
+the regular expression @var{type_regexp}.
+If @var{type_regexp} contains space(s), it should be enclosed in
+quote characters. If needed, use backslash to escape the meaning
+of special characters or quotes.
+
+If both @var{regexp} and @var{type_regexp} are provided, an argument
+is printed only if its name matches @var{regexp} and its type matches
+@var{type_regexp}.
+
+@item info locals [-q]
@kindex info locals
Print the local variables of the selected frame, each on a separate
line. These are all variables (declared either static or automatic)
accessible at the point of execution of the selected frame.
+The optional flag @samp{-q}, which stands for @samp{quiet}, disables
+printing header information and messages explaining why no local variables
+have been printed.
+
+@item info locals [-q] [-t @var{type_regexp}] [@var{regexp}]
+Like @kbd{info locals}, but only print the local variables selected
+with the provided regexp(s).
+
+If @var{regexp} is provided, print only the local variables whose names
+match the regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, print only the local variables whose
+types, as printed by the @code{whatis} command, match
+the regular expression @var{type_regexp}.
+If @var{type_regexp} contains space(s), it should be enclosed in
+quote characters. If needed, use backslash to escape the meaning
+of special characters or quotes.
+
+If both @var{regexp} and @var{type_regexp} are provided, a local variable
+is printed only if its name matches @var{regexp} and its type matches
+@var{type_regexp}.
+
+The command @kbd{info locals -q -t @var{type_regexp}} can usefully be
+combined with the commands @kbd{frame apply} and @kbd{thread apply}.
+For example, your program might use Resource Acquisition Is
+Initialization types (RAII) such as @code{lock_something_t}: each
+local variable of type @code{lock_something_t} automatically places a
+lock that is destroyed when the variable goes out of scope. You can
+then list all acquired locks in your program by doing
+@smallexample
+thread apply all -s frame apply all -s info locals -q -t lock_something_t
+@end smallexample
+@noindent
+or the equivalent shorter form
+@smallexample
+tfaas i lo -q -t lock_something_t
+@end smallexample
+
+@end table
+
+@node Frame Apply
+@section Applying a Command to Several Frames.
+@anchor{frame apply}
+@kindex frame apply
+@cindex apply command to several frames
+@table @code
+@item frame apply [all | @var{count} | @var{-count} | level @var{level}@dots{}] [@var{option}]@dots{} @var{command}
+The @code{frame apply} command allows you to apply the named
+@var{command} to one or more frames.
+
+@table @code
+@item @code{all}
+Specify @code{all} to apply @var{command} to all frames.
+
+@item @var{count}
+Use @var{count} to apply @var{command} to the innermost @var{count}
+frames, where @var{count} is a positive number.
+
+@item @var{-count}
+Use @var{-count} to apply @var{command} to the outermost @var{count}
+frames, where @var{count} is a positive number.
+
+@item @code{level}
+Use @code{level} to apply @var{command} to the set of frames identified
+by the @var{level} list. @var{level} is a frame level or a range of frame
+levels as @var{level1}-@var{level2}. The frame level is the number shown
+in the first field of the @samp{backtrace} command output.
+E.g., @samp{2-4 6-8 3} indicates to apply @var{command} for the frames
+at levels 2, 3, 4, 6, 7, 8, and then again on frame at level 3.
+
+@end table
+
+Note that the frames on which @code{frame apply} applies a command are
+also influenced by the @code{set backtrace} settings such as @code{set
+backtrace past-main} and @code{set backtrace limit N}.
+@xref{Backtrace,,Backtraces}.
+
+The @code{frame apply} command also supports a number of options that
+allow overriding relevant @code{set backtrace} settings:
+
+@table @code
+@item -past-main [@code{on}|@code{off}]
+Whether backtraces should continue past @code{main}.
+Related setting: @ref{set backtrace past-main}.
+
+@item -past-entry [@code{on}|@code{off}]
+Whether backtraces should continue past the entry point of a program.
+Related setting: @ref{set backtrace past-entry}.
+@end table
+
+By default, @value{GDBN} displays some frame information before the
+output produced by @var{command}, and an error raised during the
+execution of a @var{command} will abort @code{frame apply}. The
+following options can be used to fine-tune these behaviors:
+
+@table @code
+@item -c
+The flag @code{-c}, which stands for @samp{continue}, causes any
+errors in @var{command} to be displayed, and the execution of
+@code{frame apply} then continues.
+@item -s
+The flag @code{-s}, which stands for @samp{silent}, causes any errors
+or empty output produced by a @var{command} to be silently ignored.
+That is, the execution continues, but the frame information and errors
+are not printed.
+@item -q
+The flag @code{-q} (@samp{quiet}) disables printing the frame
+information.
@end table
+The following example shows how the flags @code{-c} and @code{-s} are
+working when applying the command @code{p j} to all frames, where
+variable @code{j} can only be successfully printed in the outermost
+@code{#1 main} frame.
+
+@smallexample
+@group
+(gdb) frame apply all p j
+#0 some_function (i=5) at fun.c:4
+No symbol "j" in current context.
+(gdb) frame apply all -c p j
+#0 some_function (i=5) at fun.c:4
+No symbol "j" in current context.
+#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11
+$1 = 5
+(gdb) frame apply all -s p j
+#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11
+$2 = 5
+(gdb)
+@end group
+@end smallexample
+
+By default, @samp{frame apply}, prints the frame location
+information before the command output:
+
+@smallexample
+@group
+(gdb) frame apply all p $sp
+#0 some_function (i=5) at fun.c:4
+$4 = (void *) 0xffffd1e0
+#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11
+$5 = (void *) 0xffffd1f0
+(gdb)
+@end group
+@end smallexample
+
+If the flag @code{-q} is given, no frame information is printed:
+@smallexample
+@group
+(gdb) frame apply all -q p $sp
+$12 = (void *) 0xffffd1e0
+$13 = (void *) 0xffffd1f0
+(gdb)
+@end group
+@end smallexample
+
+@end table
+
+@table @code
+
+@kindex faas
+@cindex apply a command to all frames (ignoring errors and empty output)
+@item faas @var{command}
+Shortcut for @code{frame apply all -s @var{command}}.
+Applies @var{command} on all frames, ignoring errors and empty output.
+
+It can for example be used to print a local variable or a function
+argument without knowing the frame where this variable or argument
+is, using:
+@smallexample
+(@value{GDBP}) faas p some_local_var_i_do_not_remember_where_it_is
+@end smallexample
+
+The @code{faas} command accepts the same options as the @code{frame
+apply} command. @xref{frame apply}.
+
+Note that the command @code{tfaas @var{command}} applies @var{command}
+on all frames of all threads. See @xref{Threads,,Threads}.
+@end table
+
+
@node Frame Filter Management
@section Management of Frame Filters.
@cindex managing frame filters
Specifies the line that begins the body of the function @var{function}.
For example, in C, this is the line with the open brace.
+By default, in C@t{++} and Ada, @var{function} is interpreted as
+specifying all functions named @var{function} in all scopes. For
+C@t{++}, this means in all namespaces and classes. For Ada, this
+means in all packages.
+
+For example, assuming a program with C@t{++} symbols named
+@code{A::B::func} and @code{B::func}, both commands @w{@kbd{break
+func}} and @w{@kbd{break B::func}} set a breakpoint on both symbols.
+
+Commands that accept a linespec let you override this with the
+@code{-qualified} option. For example, @w{@kbd{break -qualified
+func}} sets a breakpoint on a free-function named @code{func} ignoring
+any C@t{++} class methods and namespace functions called @code{func}.
+
+@xref{Explicit Locations}.
+
@item @var{function}:@var{label}
Specifies the line where @var{label} appears in @var{function}.
or @code{-line}) refer to the line that begins the body of the function.
In C, for example, this is the line with the open brace.
+By default, in C@t{++} and Ada, @var{function} is interpreted as
+specifying all functions named @var{function} in all scopes. For
+C@t{++}, this means in all namespaces and classes. For Ada, this
+means in all packages.
+
+For example, assuming a program with C@t{++} symbols named
+@code{A::B::func} and @code{B::func}, both commands @w{@kbd{break
+-function func}} and @w{@kbd{break -function B::func}} set a
+breakpoint on both symbols.
+
+You can use the @kbd{-qualified} flag to override this (see below).
+
+@item -qualified
+
+This flag makes @value{GDBN} interpret a function name specified with
+@kbd{-function} as a complete fully-qualified name.
+
+For example, assuming a C@t{++} program with symbols named
+@code{A::B::func} and @code{B::func}, the @w{@kbd{break -qualified
+-function B::func}} command sets a breakpoint on @code{B::func}, only.
+
+(Note: the @kbd{-qualified} option can precede a linespec as well
+(@pxref{Linespec Locations}), so the particular example above could be
+simplified as @w{@kbd{break -qualified B::func}}.)
+
@item -label @var{label}
The value specifies the name of a label. When the function
name is not specified, the label is searched in the function of the currently
@end table
Explicit location options may be abbreviated by omitting any non-unique
-trailing characters from the option name, e.g., @code{break -s main.c -li 3}.
+trailing characters from the option name, e.g., @w{@kbd{break -s main.c -li 3}}.
@node Address Locations
@subsection Address Locations
in the list, until it finds a file with the desired name.
For example, suppose an executable references the file
-@file{/usr/src/foo-1.0/lib/foo.c}, and our source path is
-@file{/mnt/cross}. The file is first looked up literally; if this
-fails, @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} is tried; if this
-fails, @file{/mnt/cross/foo.c} is opened; if this fails, an error
-message is printed. @value{GDBN} does not look up the parts of the
+@file{/usr/src/foo-1.0/lib/foo.c}, does not record a compilation
+directory, and the @dfn{source path} is @file{/mnt/cross}.
+@value{GDBN} would look for the source file in the following
+locations:
+
+@enumerate
+
+@item @file{/usr/src/foo-1.0/lib/foo.c}
+@item @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c}
+@item @file{/mnt/cross/foo.c}
+
+@end enumerate
+
+If the source file is not present at any of the above locations then
+an error is printed. @value{GDBN} does not look up the parts of the
source file name, such as @file{/mnt/cross/src/foo-1.0/lib/foo.c}.
Likewise, the subdirectories of the source path are not searched: if
the source path is @file{/mnt/cross}, and the binary refers to
@file{/mnt/cross/usr/src/foo-1.0/lib}.
Plain file names, relative file names with leading directories, file
-names containing dots, etc.@: are all treated as described above; for
-instance, if the source path is @file{/mnt/cross}, and the source file
-is recorded as @file{../lib/foo.c}, @value{GDBN} would first try
-@file{../lib/foo.c}, then @file{/mnt/cross/../lib/foo.c}, and after
-that---@file{/mnt/cross/foo.c}.
+names containing dots, etc.@: are all treated as described above,
+except that non-absolute file names are not looked up literally. If
+the @dfn{source path} is @file{/mnt/cross}, the source file is
+recorded as @file{../lib/foo.c}, and no compilation directory is
+recorded, then @value{GDBN} will search in the following locations:
+
+@enumerate
+
+@item @file{/mnt/cross/../lib/foo.c}
+@item @file{/mnt/cross/foo.c}
+
+@end enumerate
+
+@kindex cdir
+@kindex cwd
+@vindex $cdir@r{, convenience variable}
+@vindex $cwd@r{, convenience variable}
+@cindex compilation directory
+@cindex current directory
+@cindex working directory
+@cindex directory, current
+@cindex directory, compilation
+The @dfn{source path} will always include two special entries
+@samp{$cdir} and @samp{$cwd}, these refer to the compilation directory
+(if one is recorded) and the current working directory respectively.
+
+@samp{$cdir} causes @value{GDBN} to search within the compilation
+directory, if one is recorded in the debug information. If no
+compilation directory is recorded in the debug information then
+@samp{$cdir} is ignored.
+
+@samp{$cwd} is not the same as @samp{.}---the former tracks the
+current working directory as it changes during your @value{GDBN}
+session, while the latter is immediately expanded to the current
+directory at the time you add an entry to the source path.
+
+If a compilation directory is recorded in the debug information, and
+@value{GDBN} has not found the source file after the first search
+using @dfn{source path}, then @value{GDBN} will combine the
+compilation directory and the filename, and then search for the source
+file again using the @dfn{source path}.
+
+For example, if the executable records the source file as
+@file{/usr/src/foo-1.0/lib/foo.c}, the compilation directory is
+recorded as @file{/project/build}, and the @dfn{source path} is
+@file{/mnt/cross:$cdir:$cwd} while the current working directory of
+the @value{GDBN} session is @file{/home/user}, then @value{GDBN} will
+search for the source file in the following loctions:
+
+@enumerate
+
+@item @file{/usr/src/foo-1.0/lib/foo.c}
+@item @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c}
+@item @file{/project/build/usr/src/foo-1.0/lib/foo.c}
+@item @file{/home/user/usr/src/foo-1.0/lib/foo.c}
+@item @file{/mnt/cross/project/build/usr/src/foo-1.0/lib/foo.c}
+@item @file{/project/build/project/build/usr/src/foo-1.0/lib/foo.c}
+@item @file{/home/user/project/build/usr/src/foo-1.0/lib/foo.c}
+@item @file{/mnt/cross/foo.c}
+@item @file{/project/build/foo.c}
+@item @file{/home/user/foo.c}
+
+@end enumerate
+
+If the file name in the previous example had been recorded in the
+executable as a relative path rather than an absolute path, then the
+first look up would not have occurred, but all of the remaining steps
+would be similar.
+
+When searching for source files on MS-DOS and MS-Windows, where
+absolute paths start with a drive letter (e.g.
+@file{C:/project/foo.c}), @value{GDBN} will remove the drive letter
+from the file name before appending it to a search directory from
+@dfn{source path}; for instance if the executable references the
+source file @file{C:/project/foo.c} and @dfn{source path} is set to
+@file{D:/mnt/cross}, then @value{GDBN} will search in the following
+locations for the source file:
+
+@enumerate
+
+@item @file{C:/project/foo.c}
+@item @file{D:/mnt/cross/project/foo.c}
+@item @file{D:/mnt/cross/foo.c}
+
+@end enumerate
Note that the executable search path is @emph{not} used to locate the
source files.
@kindex directory
@kindex dir
-When you start @value{GDBN}, its source path includes only @samp{cdir}
-and @samp{cwd}, in that order.
+When you start @value{GDBN}, its source path includes only @samp{$cdir}
+and @samp{$cwd}, in that order.
To add other directories, use the @code{directory} command.
The search path is used to find both program source files and @value{GDBN}
whitespace. You may specify a directory that is already in the source
path; this moves it forward, so @value{GDBN} searches it sooner.
-@kindex cdir
-@kindex cwd
-@vindex $cdir@r{, convenience variable}
-@vindex $cwd@r{, convenience variable}
-@cindex compilation directory
-@cindex current directory
-@cindex working directory
-@cindex directory, current
-@cindex directory, compilation
-You can use the string @samp{$cdir} to refer to the compilation
-directory (if one is recorded), and @samp{$cwd} to refer to the current
-working directory. @samp{$cwd} is not the same as @samp{.}---the former
-tracks the current working directory as it changes during your @value{GDBN}
-session, while the latter is immediately expanded to the current
-directory at the time you add an entry to the source path.
+The special strings @samp{$cdir} (to refer to the compilation
+directory, if one is recorded), and @samp{$cwd} (to refer to the
+current working directory) can also be included in the list of
+directories @var{dirname}. Though these will already be in the source
+path they will be moved forward in the list so @value{GDBN} searches
+them sooner.
@item directory
Reset the source path to its default value (@samp{$cdir:$cwd} on Unix systems). This requires confirmation.
@table @code
@kindex info line
-@item info line @var{location}
+@item info line
+@itemx info line @var{location}
Print the starting and ending addresses of the compiled code for
source line @var{location}. You can specify source lines in any of
-the ways documented in @ref{Specify Location}.
+the ways documented in @ref{Specify Location}. With no @var{location}
+information about the current source line is printed.
@end table
For example, we can use @code{info line} to discover the location of
the object code for the first line of function
@code{m4_changequote}:
-@c FIXME: I think this example should also show the addresses in
-@c symbolic form, as they usually would be displayed.
@smallexample
(@value{GDBP}) info line m4_changequote
-Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
+Line 895 of "builtin.c" starts at pc 0x634c <m4_changequote> and \
+ ends at 0x6350 <m4_changequote+4>.
@end smallexample
@noindent
@var{location}) what source line covers a particular address:
@smallexample
(@value{GDBP}) info line *0x63ff
-Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
+Line 926 of "builtin.c" starts at pc 0x63e4 <m4_changequote+152> and \
+ ends at 0x6404 <m4_changequote+184>.
@end smallexample
@cindex @code{$_} and @code{info line}
convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience
Variables}).
+@cindex info line, repeated calls
+After @code{info line}, using @code{info line} again without
+specifying a location will display information about the next source
+line.
+
@table @code
@kindex disassemble
@cindex assembly instructions
location of the relocation table. On some architectures, @value{GDBN}
might be able to resolve these to actual function names.
+@table @code
+@kindex set disassembler-options
+@cindex disassembler options
+@item set disassembler-options @var{option1}[,@var{option2}@dots{}]
+This command controls the passing of target specific information to
+the disassembler. For a list of valid options, please refer to the
+@code{-M}/@code{--disassembler-options} section of the @samp{objdump}
+manual and/or the output of @kbd{objdump --help}
+(@pxref{objdump,,objdump,binutils,The GNU Binary Utilities}).
+The default value is the empty string.
+
+If it is necessary to specify more than one disassembler option, then
+multiple options can be placed together into a comma separated list.
+Currently this command is only supported on targets ARM, MIPS, PowerPC
+and S/390.
+
+@kindex show disassembler-options
+@item show disassembler-options
+Show the current setting of the disassembler options.
+@end table
+
@table @code
@kindex set disassembly-flavor
@cindex Intel disassembly flavor
Python-based pretty-printer (@pxref{Pretty Printing}).
@table @code
-@item print @var{expr}
-@itemx print /@var{f} @var{expr}
+@item print [[@var{options}] --] @var{expr}
+@itemx print [[@var{options}] --] /@var{f} @var{expr}
@var{expr} is an expression (in the source language). By default the
value of @var{expr} is printed in a format appropriate to its data type;
you can choose a different format by specifying @samp{/@var{f}}, where
@var{f} is a letter specifying the format; see @ref{Output Formats,,Output
Formats}.
-@item print
-@itemx print /@var{f}
+@anchor{print options}
+The @code{print} command supports a number of options that allow
+overriding relevant global print settings as set by @code{set print}
+subcommands:
+
+@table @code
+@item -address [@code{on}|@code{off}]
+Set printing of addresses.
+Related setting: @ref{set print address}.
+
+@item -array [@code{on}|@code{off}]
+Pretty formatting of arrays.
+Related setting: @ref{set print array}.
+
+@item -array-indexes [@code{on}|@code{off}]
+Set printing of array indexes.
+Related setting: @ref{set print array-indexes}.
+
+@item -elements @var{number-of-elements}|@code{unlimited}
+Set limit on string chars or array elements to print. The value
+@code{unlimited} causes there to be no limit. Related setting:
+@ref{set print elements}.
+
+@item -max-depth @var{depth}|@code{unlimited}
+Set the threshold after which nested structures are replaced with
+ellipsis. Related setting: @ref{set print max-depth}.
+
+@item -null-stop [@code{on}|@code{off}]
+Set printing of char arrays to stop at first null char. Related
+setting: @ref{set print null-stop}.
+
+@item -object [@code{on}|@code{off}]
+Set printing C@t{++} virtual function tables. Related setting:
+@ref{set print object}.
+
+@item -pretty [@code{on}|@code{off}]
+Set pretty formatting of structures. Related setting: @ref{set print
+pretty}.
+
+@item -repeats @var{number-of-repeats}|@code{unlimited}
+Set threshold for repeated print elements. @code{unlimited} causes
+all elements to be individually printed. Related setting: @ref{set
+print repeats}.
+
+@item -static-members [@code{on}|@code{off}]
+Set printing C@t{++} static members. Related setting: @ref{set print
+static-members}.
+
+@item -symbol [@code{on}|@code{off}]
+Set printing of symbol names when printing pointers. Related setting:
+@ref{set print symbol}.
+
+@item -union [@code{on}|@code{off}]
+Set printing of unions interior to structures. Related setting:
+@ref{set print union}.
+
+@item -vtbl [@code{on}|@code{off}]
+Set printing of C++ virtual function tables. Related setting:
+@ref{set print vtbl}.
+@end table
+
+Because the @code{print} command accepts arbitrary expressions which
+may look like options (including abbreviations), if you specify any
+command option, then you must use a double dash (@code{--}) to mark
+the end of option processing.
+
+For example, this prints the value of the @code{-r} expression:
+
+@smallexample
+(@value{GDBP}) print -r
+@end smallexample
+
+While this repeats the last value in the value history (see below)
+with the @code{-raw} option in effect:
+
+@smallexample
+(@value{GDBP}) print -r --
+@end smallexample
+
+Here is an example including both on option and an expression:
+
+@smallexample
+@group
+(@value{GDBP}) print -pretty -- *myptr
+$1 = @{
+ next = 0x0,
+ flags = @{
+ sweet = 1,
+ sour = 1
+ @},
+ meat = 0x54 "Pork"
+@}
+@end group
+@end smallexample
+
+@item print [@var{options}]
+@itemx print [@var{options}] /@var{f}
@cindex reprint the last value
If you omit @var{expr}, @value{GDBN} displays the last value again (from the
@dfn{value history}; @pxref{Value History, ,Value History}). This allows you to
by the debug information, @value{GDBN} will say @samp{<incomplete
type>}. @xref{Symbols, incomplete type}, for more about this.
+@cindex no debug info variables
+If you try to examine or use the value of a (global) variable for
+which @value{GDBN} has no type information, e.g., because the program
+includes no debug information, @value{GDBN} displays an error message.
+@xref{Symbols, unknown type}, for more about unknown types. If you
+cast the variable to its declared type, @value{GDBN} gets the
+variable's value using the cast-to type as the variable's type. For
+example, in a C program:
+
+@smallexample
+ (@value{GDBP}) p var
+ 'var' has unknown type; cast it to its declared type
+ (@value{GDBP}) p (float) var
+ $1 = 3.14
+@end smallexample
+
If you append @kbd{@@entry} string to a function parameter name you get its
value at the time the function got called. If the value is not available an
error message is printed. Entry values are available only with some compilers.
@table @code
@kindex set print
+@anchor{set print address}
@item set print address
@itemx set print address on
@cindex print/don't print memory addresses
You can also enable @samp{/a}-like formatting all the time using
@samp{set print symbol on}:
+@anchor{set print symbol}
@table @code
@item set print symbol on
Tell @value{GDBN} to print the symbol corresponding to an address, if
Other settings control how different kinds of objects are printed:
@table @code
+@anchor{set print array}
@item set print array
@itemx set print array on
@cindex pretty print arrays
arrays.
@cindex print array indexes
+@anchor{set print array-indexes}
@item set print array-indexes
@itemx set print array-indexes on
Print the index of each element when displaying arrays. May be more
Show whether the index of each element is printed when displaying
arrays.
+@anchor{set print elements}
@item set print elements @var{number-of-elements}
@itemx set print elements unlimited
@cindex number of array elements to print
Display the number of elements of a large array that @value{GDBN} will print.
If the number is 0, then the printing is unlimited.
+@anchor{set print frame-arguments}
@item set print frame-arguments @var{value}
@kindex set print frame-arguments
@cindex printing frame argument values
@cindex print all frame argument values
@cindex print frame argument values for scalars only
-@cindex do not print frame argument values
+@cindex do not print frame arguments
This command allows to control how the values of arguments are printed
when the debugger prints a frame (@pxref{Frames}). The possible
values are:
#1 0x08048361 in call_me (i=@dots{}, s=@dots{}, ss=@dots{}, u=@dots{}, e=@dots{})
at frame-args.c:23
@end smallexample
+
+@item presence
+Only the presence of arguments is indicated by @code{@dots{}}.
+The @code{@dots{}} are not printed for function without any arguments.
+None of the argument names and values are printed.
+In this case, the example above now becomes:
+
+@smallexample
+#1 0x08048361 in call_me (@dots{}) at frame-args.c:23
+@end smallexample
+
@end table
By default, only scalar arguments are printed. This command can be used
Also, it improves performance when displaying Ada frames, because
the computation of large arguments can sometimes be CPU-intensive,
especially in large applications. Setting @code{print frame-arguments}
-to @code{scalars} (the default) or @code{none} avoids this computation,
-thus speeding up the display of each Ada frame.
+to @code{scalars} (the default), @code{none} or @code{presence} avoids
+this computation, thus speeding up the display of each Ada frame.
@item show print frame-arguments
Show how the value of arguments should be displayed when printing a frame.
-@item set print raw frame-arguments on
+@anchor{set print raw-frame-arguments}
+@item set print raw-frame-arguments on
Print frame arguments in raw, non pretty-printed, form.
-@item set print raw frame-arguments off
+@item set print raw-frame-arguments off
Print frame arguments in pretty-printed form, if there is a pretty-printer
for the value (@pxref{Pretty Printing}),
otherwise print the value in raw form.
This is the default.
-@item show print raw frame-arguments
+@item show print raw-frame-arguments
Show whether to print frame arguments in raw form.
@anchor{set print entry-values}
@code{no} setting.
This functionality is currently supported only by DWARF 2 debugging format and
-the compiler has to produce @samp{DW_TAG_GNU_call_site} tags. With
+the compiler has to produce @samp{DW_TAG_call_site} tags. With
@value{NGCC}, you need to specify @option{-O -g} during compilation, to get
this information.
Show the method being used for printing of frame argument values at function
entry.
+@anchor{set print frame-info}
+@item set print frame-info @var{value}
+@kindex set print frame-info
+@cindex printing frame information
+@cindex frame information, printing
+This command allows to control the information printed when
+the debugger prints a frame. See @ref{Frames}, @ref{Backtrace},
+for a general explanation about frames and frame information.
+Note that some other settings (such as @code{set print frame-arguments}
+and @code{set print address}) are also influencing if and how some frame
+information is displayed. In particular, the frame program counter is never
+printed if @code{set print address} is off.
+
+The possible values for @code{set print frame-info} are:
+@table @code
+@item short-location
+Print the frame level, the program counter (if not at the
+beginning of the location source line), the function, the function
+arguments.
+@item location
+Same as @code{short-location} but also print the source file and source line
+number.
+@item location-and-address
+Same as @code{location} but print the program counter even if located at the
+beginning of the location source line.
+@item source-line
+Print the program counter (if not at the beginning of the location
+source line), the line number and the source line.
+@item source-and-location
+Print what @code{location} and @code{source-line} are printing.
+@item auto
+The information printed for a frame is decided automatically
+by the @value{GDBN} command that prints a frame.
+For example, @code{frame} prints the information printed by
+@code{source-and-location} while @code{stepi} will switch between
+@code{source-line} and @code{source-and-location} depending on the program
+counter.
+The default value is @code{auto}.
+@end table
+
+@anchor{set print repeats}
@item set print repeats @var{number-of-repeats}
@itemx set print repeats unlimited
@cindex repeated array elements
Display the current threshold for printing repeated identical
elements.
+@anchor{set print max-depth}
+@item set print max-depth @var{depth}
+@item set print max-depth unlimited
+@cindex printing nested structures
+Set the threshold after which nested structures are replaced with
+ellipsis, this can make visualising deeply nested structures easier.
+
+For example, given this C code
+
+@smallexample
+typedef struct s1 @{ int a; @} s1;
+typedef struct s2 @{ s1 b; @} s2;
+typedef struct s3 @{ s2 c; @} s3;
+typedef struct s4 @{ s3 d; @} s4;
+
+s4 var = @{ @{ @{ @{ 3 @} @} @} @};
+@end smallexample
+
+The following table shows how different values of @var{depth} will
+effect how @code{var} is printed by @value{GDBN}:
+
+@multitable @columnfractions .3 .7
+@headitem @var{depth} setting @tab Result of @samp{p var}
+@item unlimited
+@tab @code{$1 = @{d = @{c = @{b = @{a = 3@}@}@}@}}
+@item @code{0}
+@tab @code{$1 = @{...@}}
+@item @code{1}
+@tab @code{$1 = @{d = @{...@}@}}
+@item @code{2}
+@tab @code{$1 = @{d = @{c = @{...@}@}@}}
+@item @code{3}
+@tab @code{$1 = @{d = @{c = @{b = @{...@}@}@}@}}
+@item @code{4}
+@tab @code{$1 = @{d = @{c = @{b = @{a = 3@}@}@}@}}
+@end multitable
+
+To see the contents of structures that have been hidden the user can
+either increase the print max-depth, or they can print the elements of
+the structure that are visible, for example
+
+@smallexample
+(gdb) set print max-depth 2
+(gdb) p var
+$1 = @{d = @{c = @{...@}@}@}
+(gdb) p var.d
+$2 = @{c = @{b = @{...@}@}@}
+(gdb) p var.d.c
+$3 = @{b = @{a = 3@}@}
+@end smallexample
+
+The pattern used to replace nested structures varies based on
+language, for most languages @code{@{...@}} is used, but Fortran uses
+@code{(...)}.
+
+@item show print max-depth
+Display the current threshold after which nested structures are
+replaces with ellipsis.
+
+@anchor{set print null-stop}
@item set print null-stop
@cindex @sc{null} elements in arrays
Cause @value{GDBN} to stop printing the characters of an array when the first
Show whether @value{GDBN} stops printing an array on the first
@sc{null} character.
+@anchor{set print pretty}
@item set print pretty on
@cindex print structures in indented form
@cindex indentation in structure display
@item show print sevenbit-strings
Show whether or not @value{GDBN} is printing only seven-bit characters.
+@anchor{set print union}
@item set print union on
@cindex unions in structures, printing
Tell @value{GDBN} to print unions which are contained in structures
@cindex symbol decoding style, C@t{++}
@kindex set demangle-style
@item set demangle-style @var{style}
-Choose among several encoding schemes used by different compilers to
-represent C@t{++} names. The choices for @var{style} are currently:
-
-@table @code
-@item auto
-Allow @value{GDBN} to choose a decoding style by inspecting your program.
-This is the default.
-
-@item gnu
-Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm.
-
-@item hp
-Decode based on the HP ANSI C@t{++} (@code{aCC}) encoding algorithm.
-
-@item lucid
-Decode based on the Lucid C@t{++} compiler (@code{lcc}) encoding algorithm.
-
-@item arm
-Decode using the algorithm in the @cite{C@t{++} Annotated Reference Manual}.
-@strong{Warning:} this setting alone is not sufficient to allow
-debugging @code{cfront}-generated executables. @value{GDBN} would
-require further enhancement to permit that.
-
-@end table
-If you omit @var{style}, you will see a list of possible formats.
+Choose among several encoding schemes used by different compilers to represent
+C@t{++} names. If you omit @var{style}, you will see a list of possible
+formats. The default value is @var{auto}, which lets @value{GDBN} choose a
+decoding style by inspecting your program.
@item show demangle-style
Display the encoding style currently in use for decoding C@t{++} symbols.
+@anchor{set print object}
@item set print object
@itemx set print object on
@cindex derived type of an object, printing
@item show print object
Show whether actual, or declared, object types are displayed.
+@anchor{set print static-members}
@item set print static-members
@itemx set print static-members on
@cindex static members of C@t{++} objects
Show whether Pascal static members are printed or not.
@c These don't work with HP ANSI C++ yet.
+@anchor{set print vtbl}
@item set print vtbl
@itemx set print vtbl on
@cindex pretty print C@t{++} virtual function tables
bar
bar1
bar2
-(gdb) disable pretty-printer library2 bar:bar1
+(gdb) disable pretty-printer library2 bar;bar1
1 printer disabled
1 of 3 printers enabled
(gdb) info pretty-printer library2
The variable @code{$_exception} is set to the exception object being
thrown at an exception-related catchpoint. @xref{Set Catchpoints}.
+@item $_ada_exception
+The variable @code{$_ada_exception} is set to the address of the
+exception being caught or thrown at an Ada exception-related
+catchpoint. @xref{Set Catchpoints}.
+
@item $_probe_argc
@itemx $_probe_arg0@dots{}$_probe_arg11
Arguments to a static probe. @xref{Static Probe Points}.
@vindex $_tlb@r{, convenience variable}
The variable @code{$_tlb} is automatically set when debugging
applications running on MS-Windows in native mode or connected to
-gdbserver that supports the @code{qGetTIBAddr} request.
+gdbserver that supports the @code{qGetTIBAddr} request.
@xref{General Query Packets}.
This variable contains the address of the thread information block.
@item $_gthread
The global number of the current thread. @xref{global thread numbers}.
+@item $_gdb_major
+@itemx $_gdb_minor
+@vindex $_gdb_major@r{, convenience variable}
+@vindex $_gdb_minor@r{, convenience variable}
+The major and minor version numbers of the running @value{GDBN}.
+Development snapshots and pretest versions have their minor version
+incremented by one; thus, @value{GDBN} pretest 9.11.90 will produce
+the value 12 for @code{$_gdb_minor}. These variables allow you to
+write scripts that work with different versions of @value{GDBN}
+without errors caused by features unavailable in some of those
+versions.
+
+@item $_shell_exitcode
+@itemx $_shell_exitsignal
+@vindex $_shell_exitcode@r{, convenience variable}
+@vindex $_shell_exitsignal@r{, convenience variable}
+@cindex shell command, exit code
+@cindex shell command, exit signal
+@cindex exit status of shell commands
+@value{GDBN} commands such as @code{shell} and @code{|} are launching
+shell commands. When a launched command terminates, @value{GDBN}
+automatically maintains the variables @code{$_shell_exitcode}
+and @code{$_shell_exitsignal} according to the exit status of the last
+launched command. These variables are set and used similarly to
+the variables @code{$_exitcode} and @code{$_exitsignal}.
+
@end table
@node Convenience Funs
$4 = 1
@end smallexample
+@item $_gdb_setting_str (@var{setting})
+@findex $_gdb_setting_str@r{, convenience function}
+Return the value of the @value{GDBN} @var{setting} as a string.
+@var{setting} is any setting that can be used in a @code{set} or
+@code{show} command (@pxref{Controlling GDB}).
+
+@smallexample
+(@value{GDBP}) show print frame-arguments
+Printing of non-scalar frame arguments is "scalars".
+(@value{GDBP}) p $_gdb_setting_str("print frame-arguments")
+$1 = "scalars"
+(@value{GDBP}) p $_gdb_setting_str("height")
+$2 = "30"
+(@value{GDBP})
+@end smallexample
+
+@item $_gdb_setting (@var{setting})
+@findex $_gdb_setting@r{, convenience function}
+Return the value of the @value{GDBN} @var{setting}.
+The type of the returned value depends on the setting.
+
+The value type for boolean and auto boolean settings is @code{int}.
+The boolean values @code{off} and @code{on} are converted to
+the integer values @code{0} and @code{1}. The value @code{auto} is
+converted to the value @code{-1}.
+
+The value type for integer settings is either @code{unsigned int}
+or @code{int}, depending on the setting.
+
+Some integer settings accept an @code{unlimited} value.
+Depending on the setting, the @code{set} command also accepts
+the value @code{0} or the value @code{@minus{}1} as a synonym for
+@code{unlimited}.
+For example, @code{set height unlimited} is equivalent to
+@code{set height 0}.
+
+Some other settings that accept the @code{unlimited} value
+use the value @code{0} to literally mean zero.
+For example, @code{set history size 0} indicates to not
+record any @value{GDBN} commands in the command history.
+For such settings, @code{@minus{}1} is the synonym
+for @code{unlimited}.
+
+See the documentation of the corresponding @code{set} command for
+the numerical value equivalent to @code{unlimited}.
+
+The @code{$_gdb_setting} function converts the unlimited value
+to a @code{0} or a @code{@minus{}1} value according to what the
+@code{set} command uses.
+
+@smallexample
+@group
+(@value{GDBP}) p $_gdb_setting_str("height")
+$1 = "30"
+(@value{GDBP}) p $_gdb_setting("height")
+$2 = 30
+(@value{GDBP}) set height unlimited
+(@value{GDBP}) p $_gdb_setting_str("height")
+$3 = "unlimited"
+(@value{GDBP}) p $_gdb_setting("height")
+$4 = 0
+@end group
+@group
+(@value{GDBP}) p $_gdb_setting_str("history size")
+$5 = "unlimited"
+(@value{GDBP}) p $_gdb_setting("history size")
+$6 = -1
+(@value{GDBP}) p $_gdb_setting_str("disassemble-next-line")
+$7 = "auto"
+(@value{GDBP}) p $_gdb_setting("disassemble-next-line")
+$8 = -1
+(@value{GDBP})
+@end group
+@end smallexample
+
+Other setting types (enum, filename, optional filename, string, string noescape)
+are returned as string values.
+
+
+@item $_gdb_maint_setting_str (@var{setting})
+@findex $_gdb_maint_setting_str@r{, convenience function}
+Like the @code{$_gdb_setting_str} function, but works with
+@code{maintenance set} variables.
+
+@item $_gdb_maint_setting (@var{setting})
+@findex $_gdb_maint_setting@r{, convenience function}
+Like the @code{$_gdb_setting} function, but works with
+@code{maintenance set} variables.
+
@end table
-These functions require @value{GDBN} to be configured with
+The following functions require @value{GDBN} to be configured with
@code{Python} support.
@table @code
Visiting node of type NODE_INTEGER
@end smallexample
+@item $_cimag(@var{value})
+@itemx $_creal(@var{value})
+@findex $_cimag@r{, convenience function}
+@findex $_creal@r{, convenience function}
+Return the imaginary (@code{$_cimag}) or real (@code{$_creal}) part of
+the complex number @var{value}.
+
+The type of the imaginary or real part depends on the type of the
+complex number, e.g., using @code{$_cimag} on a @code{float complex}
+will return an imaginary part of type @code{float}.
+
@end table
@value{GDBN} provides the ability to list and get help on
Print the names and values of all registers, including floating-point
and vector registers (in the selected stack frame).
+@item info registers @var{reggroup} @dots{}
+Print the name and value of the registers in each of the specified
+@var{reggroup}s. The @var{reggoup} can be any of those returned by
+@code{maint print reggroups} (@pxref{Maintenance Commands}).
+
@item info registers @var{regname} @dots{}
Print the @dfn{relativized} value of each specified register @var{regname}.
As discussed in detail below, register values are normally relative to
On @sc{gnu}/Linux, this command can take into account the value of the
file @file{/proc/@var{pid}/coredump_filter} when generating the core
-dump (@pxref{set use-coredump-filter}).
+dump (@pxref{set use-coredump-filter}), and by default honors the
+@code{VM_DONTDUMP} flag for mappings where it is present in the file
+@file{/proc/@var{pid}/smaps} (@pxref{set dump-excluded-mappings}).
@kindex set use-coredump-filter
@anchor{set use-coredump-filter}
(anonymous private mappings), @code{1} (anonymous shared mappings),
@code{4} (ELF headers) and @code{5} (private huge pages) are active.
This will cause these memory mappings to be dumped automatically.
+
+@kindex set dump-excluded-mappings
+@anchor{set dump-excluded-mappings}
+@item set dump-excluded-mappings on
+@itemx set dump-excluded-mappings off
+If @code{on} is specified, @value{GDBN} will dump memory mappings
+marked with the @code{VM_DONTDUMP} flag. This flag is represented in
+the file @file{/proc/@var{pid}/smaps} with the acronym @code{dd}.
+
+The default value is @code{off}.
@end table
@node Character Sets
All values are interpreted in the current language.
This means, for example, that if the current source language is C/C@t{++}
then searching for the string ``hello'' includes the trailing '\0'.
+The null terminator can be removed from searching by using casts,
+e.g.: @samp{@{char[5]@}"hello"}.
If the value size is not specified, it is taken from the
value's type in the current language.
(gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o'
0x8049567 <hello.1620>
0x804956d <hello.1620+6>
-2 patterns found
+2 patterns found.
+(gdb) find &hello[0], +sizeof(hello), @{char[5]@}"hello"
+0x8049567 <hello.1620>
+0x804956d <hello.1620+6>
+2 patterns found.
(gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l'
0x8049567 <hello.1620>
1 pattern found
return address set up as if @code{B} called @code{C} normally.
This functionality is currently supported only by DWARF 2 debugging format and
-the compiler has to produce @samp{DW_TAG_GNU_call_site} tags. With
+the compiler has to produce @samp{DW_TAG_call_site} tags. With
@value{NGCC}, you need to specify @option{-O -g} during compilation, to get
this information.
static void __attribute__((noinline, noclone)) c (void) @{ a (); @}
int main (void) @{ x (); return 0; @}
-Breakpoint 1, DW_OP_GNU_entry_value resolving cannot find
-DW_TAG_GNU_call_site 0x40039a in main
+Breakpoint 1, DW_OP_entry_value resolving cannot find
+DW_TAG_call_site 0x40039a in main
a () at t.c:3
3 static void __attribute__((noinline, noclone)) a (void) @{ x++; @}
(gdb) bt
(gdb) bt
#0 c (i=i@@entry=0) at t.c:2
-#1 0x0000000000400428 in a (DW_OP_GNU_entry_value resolving has found
+#1 0x0000000000400428 in a (DW_OP_entry_value resolving has found
function "a" at 0x400420 can call itself via tail calls
i=<optimized out>) at t.c:6
#2 0x000000000040036e in main () at t.c:7
@cindex reference declarations
@item
-@value{GDBN} understands variables declared as C@t{++} references; you can use
-them in expressions just as you do in C@t{++} source---they are automatically
-dereferenced.
+@value{GDBN} understands variables declared as C@t{++} lvalue or rvalue
+references; you can use them in expressions just as you do in C@t{++}
+source---they are automatically dereferenced.
In the parameter list shown when @value{GDBN} displays a frame, the values of
reference variables are not displayed (unlike other variables); this
also use the @value{GDBN} command-line word completion facilities to list the
available choices, or to finish the type list for you.
@xref{Completion,, Command Completion}, for details on how to do this.
+
+@item @r{Breakpoints in functions with ABI tags}
+
+The GNU C@t{++} compiler introduced the notion of ABI ``tags'', which
+correspond to changes in the ABI of a type, function, or variable that
+would not otherwise be reflected in a mangled name. See
+@url{https://developers.redhat.com/blog/2015/02/05/gcc5-and-the-c11-abi/}
+for more detail.
+
+The ABI tags are visible in C@t{++} demangled names. For example, a
+function that returns a std::string:
+
+@smallexample
+std::string function(int);
+@end smallexample
+
+@noindent
+when compiled for the C++11 ABI is marked with the @code{cxx11} ABI
+tag, and @value{GDBN} displays the symbol like this:
+
+@smallexample
+function[abi:cxx11](int)
+@end smallexample
+
+You can set a breakpoint on such functions simply as if they had no
+tag. For example:
+
+@smallexample
+(gdb) b function(int)
+Breakpoint 2 at 0x40060d: file main.cc, line 10.
+(gdb) info breakpoints
+Num Type Disp Enb Address What
+1 breakpoint keep y 0x0040060d in function[abi:cxx11](int)
+ at main.cc:10
+@end smallexample
+
+On the rare occasion you need to disambiguate between different ABI
+tags, you can do so by simply including the ABI tag in the function
+name, like:
+
+@smallexample
+(@value{GDBP}) b ambiguous[abi:other_tag](int)
+@end smallexample
@end table
@node Decimal Floating Point
types. Also suitable for unions. As unions aren't part of regular Fortran,
this can only happen when accessing a register that uses a gdbarch-defined
union type.
+@item ::
+The scope operator. Normally used to access variables in modules or
+to set breakpoints on subroutines nested in modules or in other
+subroutines (internal subroutines).
@end table
@node Fortran Defaults
@item
Method calls cannot be made via traits.
-@item
-Trait objects cannot be created or inspected.
-
@item
Operator overloading is not implemented.
* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files
* Ravenscar Profile:: Tasking Support when using the Ravenscar
Profile
+* Ada Settings:: New settable GDB parameters for Ada.
* Ada Glitches:: Known peculiarities of Ada mode.
@end menu
* 2 807c468 1 15 Runnable task_1
(@value{GDBP}) info task 2
Ada Task: 0x807c468
-Name: task_1
-Thread: 0x807f378
-Parent: 1 (main_task)
+Name: "task_1"
+Thread: 0
+LWP: 0x1fac
+Parent: 1 ("main_task")
Base Priority: 15
State: Runnable
@end smallexample
@item task
@kindex task@r{ (Ada)}
@cindex current Ada task ID
-This command prints the ID of the current task.
+This command prints the ID and name of the current task.
@smallexample
@iftex
(@value{GDBP}) info tasks
ID TID P-ID Pri State Name
1 8077870 0 15 Child Activation Wait main_task
-* 2 807c458 1 15 Runnable t
+* 2 807c458 1 15 Runnable some_task
(@value{GDBP}) task
-[Current task is 2]
+[Current task is 2 "some_task"]
@end smallexample
@item task @var{taskno}
(@value{GDBP}) info tasks
ID TID P-ID Pri State Name
1 8077870 0 15 Child Activation Wait main_task
-* 2 807c458 1 15 Runnable t
+* 2 807c458 1 15 Runnable some_task
(@value{GDBP}) task 1
-[Switching to task 1]
+[Switching to task 1 "main_task"]
#0 0x8067726 in pthread_cond_wait ()
(@value{GDBP}) bt
#0 0x8067726 in pthread_cond_wait ()
@end table
+@node Ada Settings
+@subsubsection Ada Settings
+@cindex Ada settings
+
+@table @code
+@kindex set varsize-limit
+@item set varsize-limit @var{size}
+Prevent @value{GDBN} from attempting to evaluate objects whose size
+is above the given limit (@var{size}) when those sizes are computed
+from run-time quantities. This is typically the case when the object
+has a variable size, such as an array whose bounds are not known at
+compile time for example. Setting @var{size} to @code{unlimited}
+removes the size limitation. By default, the limit is about 65KB.
+
+The purpose of having such a limit is to prevent @value{GDBN} from
+trying to grab enormous chunks of virtual memory when asked to evaluate
+a quantity whose bounds have been corrupted or have not yet been fully
+initialized. The limit applies to the results of some subexpressions
+as well as to complete expressions. For example, an expression denoting
+a simple integer component, such as @code{x.y.z}, may fail if the size of
+@code{x.y} is variable and exceeds @code{size}. On the other hand,
+@value{GDBN} is sometimes clever; the expression @code{A(i)}, where
+@code{A} is an array variable with non-constant size, will generally
+succeed regardless of the bounds on @code{A}, as long as the component
+size is less than @var{size}.
+
+@kindex show varsize-limit
+@item show varsize-limit
+Show the limit on types whose size is determined by run-time quantities.
+@end table
+
@node Ada Glitches
@subsubsection Known Peculiarities of Ada Mode
@cindex Ada, problems
@cindex symbol names
@cindex names of symbols
@cindex quoting names
+@anchor{quoting names}
Occasionally, you may need to refer to symbols that contain unusual
characters, which @value{GDBN} ordinarily treats as word delimiters. The
most frequent case is in referring to static variables in other
This command shows the current setting of method display when printing
classes.
+@kindex set print type nested-type-limit
+@item set print type nested-type-limit @var{limit}
+@itemx set print type nested-type-limit unlimited
+Set the limit of displayed nested types that the type printer will
+show. A @var{limit} of @code{unlimited} or @code{-1} will show all
+nested definitions. By default, the type printer will not show any nested
+types defined in classes.
+
+@kindex show print type nested-type-limit
+@item show print type nested-type-limit
+This command shows the current display limit of nested types when
+printing classes.
+
@kindex set print type typedefs
@item set print type typedefs
@itemx set print type typedefs on
@item T
Print typedefs defined in the class. This is the default, but the flag
exists in case you change the default with @command{set print type typedefs}.
+
+@item o
+Print the offsets and sizes of fields in a struct, similar to what the
+@command{pahole} tool does. This option implies the @code{/tm} flags.
+
+For example, given the following declarations:
+
+@smallexample
+struct tuv
+@{
+ int a1;
+ char *a2;
+ int a3;
+@};
+
+struct xyz
+@{
+ int f1;
+ char f2;
+ void *f3;
+ struct tuv f4;
+@};
+
+union qwe
+@{
+ struct tuv fff1;
+ struct xyz fff2;
+@};
+
+struct tyu
+@{
+ int a1 : 1;
+ int a2 : 3;
+ int a3 : 23;
+ char a4 : 2;
+ int64_t a5;
+ int a6 : 5;
+ int64_t a7 : 3;
+@};
+@end smallexample
+
+Issuing a @kbd{ptype /o struct tuv} command would print:
+
+@smallexample
+(@value{GDBP}) ptype /o struct tuv
+/* offset | size */ type = struct tuv @{
+/* 0 | 4 */ int a1;
+/* XXX 4-byte hole */
+/* 8 | 8 */ char *a2;
+/* 16 | 4 */ int a3;
+
+ /* total size (bytes): 24 */
+ @}
+@end smallexample
+
+Notice the format of the first column of comments. There, you can
+find two parts separated by the @samp{|} character: the @emph{offset},
+which indicates where the field is located inside the struct, in
+bytes, and the @emph{size} of the field. Another interesting line is
+the marker of a @emph{hole} in the struct, indicating that it may be
+possible to pack the struct and make it use less space by reorganizing
+its fields.
+
+It is also possible to print offsets inside an union:
+
+@smallexample
+(@value{GDBP}) ptype /o union qwe
+/* offset | size */ type = union qwe @{
+/* 24 */ struct tuv @{
+/* 0 | 4 */ int a1;
+/* XXX 4-byte hole */
+/* 8 | 8 */ char *a2;
+/* 16 | 4 */ int a3;
+
+ /* total size (bytes): 24 */
+ @} fff1;
+/* 40 */ struct xyz @{
+/* 0 | 4 */ int f1;
+/* 4 | 1 */ char f2;
+/* XXX 3-byte hole */
+/* 8 | 8 */ void *f3;
+/* 16 | 24 */ struct tuv @{
+/* 16 | 4 */ int a1;
+/* XXX 4-byte hole */
+/* 24 | 8 */ char *a2;
+/* 32 | 4 */ int a3;
+
+ /* total size (bytes): 24 */
+ @} f4;
+
+ /* total size (bytes): 40 */
+ @} fff2;
+
+ /* total size (bytes): 40 */
+ @}
+@end smallexample
+
+In this case, since @code{struct tuv} and @code{struct xyz} occupy the
+same space (because we are dealing with an union), the offset is not
+printed for them. However, you can still examine the offset of each
+of these structures' fields.
+
+Another useful scenario is printing the offsets of a struct containing
+bitfields:
+
+@smallexample
+(@value{GDBP}) ptype /o struct tyu
+/* offset | size */ type = struct tyu @{
+/* 0:31 | 4 */ int a1 : 1;
+/* 0:28 | 4 */ int a2 : 3;
+/* 0: 5 | 4 */ int a3 : 23;
+/* 3: 3 | 1 */ signed char a4 : 2;
+/* XXX 3-bit hole */
+/* XXX 4-byte hole */
+/* 8 | 8 */ int64_t a5;
+/* 16: 0 | 4 */ int a6 : 5;
+/* 16: 5 | 8 */ int64_t a7 : 3;
+"/* XXX 7-byte padding */
+
+ /* total size (bytes): 24 */
+ @}
+@end smallexample
+
+Note how the offset information is now extended to also include the
+first bit of the bitfield.
@end table
@kindex ptype
``Incomplete type'' is C terminology for data types that are not
completely specified.
+@cindex unknown type
+Othertimes, information about a variable's type is completely absent
+from the debug information included in the program. This most often
+happens when the program or library where the variable is defined
+includes no debug information at all. @value{GDBN} knows the variable
+exists from inspecting the linker/loader symbol table (e.g., the ELF
+dynamic symbol table), but such symbols do not contain type
+information. Inspecting the type of a (global) variable for which
+@value{GDBN} has no type information shows:
+
+@smallexample
+ (@value{GDBP}) ptype var
+ type = <data variable, no debug info>
+@end smallexample
+
+@xref{Variables, no debug info variables}, for how to print the values
+of such variables.
+
@kindex info types
-@item info types @var{regexp}
-@itemx info types
+@item info types [-q] [@var{regexp}]
Print a brief description of all types whose names match the regular
expression @var{regexp} (or all types in your program, if you supply
no argument). Each complete typename is matched as though it were a
@samp{i type ^value$} gives information only on types whose complete
name is @code{value}.
+In programs using different languages, @value{GDBN} chooses the syntax
+to print the type description according to the
+@samp{set language} value: using @samp{set language auto}
+(see @ref{Automatically, ,Set Language Automatically}) means to use the
+language of the type, other values mean to use
+the manually specified language (see @ref{Manually, ,Set Language Manually}).
+
This command differs from @code{ptype} in two ways: first, like
@code{whatis}, it does not print a detailed description; second, it
-lists all source files where a type is defined.
+lists all source files and line numbers where a type is defined.
+
+The output from @samp{into types} is proceeded with a header line
+describing what types are being listed. The optional flag @samp{-q},
+which stands for @samp{quiet}, disables printing this header
+information.
@kindex info type-printers
@item info type-printers
debugging information, organized into two lists: files whose symbols
have already been read, and files whose symbols will be read when needed.
+@item info sources [-dirname | -basename] [--] [@var{regexp}]
+Like @samp{info sources}, but only print the names of the files
+matching the provided @var{regexp}.
+By default, the @var{regexp} is used to match anywhere in the filename.
+If @code{-dirname}, only files having a dirname matching @var{regexp} are shown.
+If @code{-basename}, only files having a basename matching @var{regexp}
+are shown.
+The matching is case-sensitive, except on operating systems that
+have case-insensitive filesystem (e.g., MS-Windows).
+
@kindex info functions
-@item info functions
+@item info functions [-q] [-n]
Print the names and data types of all defined functions.
-
-@item info functions @var{regexp}
-Print the names and data types of all defined functions
-whose names contain a match for regular expression @var{regexp}.
-Thus, @samp{info fun step} finds all functions whose names
-include @code{step}; @samp{info fun ^step} finds those whose names
-start with @code{step}. If a function name contains characters
-that conflict with the regular expression language (e.g.@:
+Similarly to @samp{info types}, this command groups its output by source
+files and annotates each function definition with its source line
+number.
+
+In programs using different languages, @value{GDBN} chooses the syntax
+to print the function name and type according to the
+@samp{set language} value: using @samp{set language auto}
+(see @ref{Automatically, ,Set Language Automatically}) means to use the
+language of the function, other values mean to use
+the manually specified language (see @ref{Manually, ,Set Language Manually}).
+
+The @samp{-n} flag excludes @dfn{non-debugging symbols} from the
+results. A non-debugging symbol is a symbol that comes from the
+executable's symbol table, not from the debug information (for
+example, DWARF) associated with the executable.
+
+The optional flag @samp{-q}, which stands for @samp{quiet}, disables
+printing header information and messages explaining why no functions
+have been printed.
+
+@item info functions [-q] [-n] [-t @var{type_regexp}] [@var{regexp}]
+Like @samp{info functions}, but only print the names and data types
+of the functions selected with the provided regexp(s).
+
+If @var{regexp} is provided, print only the functions whose names
+match the regular expression @var{regexp}.
+Thus, @samp{info fun step} finds all functions whose
+names include @code{step}; @samp{info fun ^step} finds those whose names
+start with @code{step}. If a function name contains characters that
+conflict with the regular expression language (e.g.@:
@samp{operator*()}), they may be quoted with a backslash.
+If @var{type_regexp} is provided, print only the functions whose
+types, as printed by the @code{whatis} command, match
+the regular expression @var{type_regexp}.
+If @var{type_regexp} contains space(s), it should be enclosed in
+quote characters. If needed, use backslash to escape the meaning
+of special characters or quotes.
+Thus, @samp{info fun -t '^int ('} finds the functions that return
+an integer; @samp{info fun -t '(.*int.*'} finds the functions that
+have an argument type containing int; @samp{info fun -t '^int (' ^step}
+finds the functions whose names start with @code{step} and that return
+int.
+
+If both @var{regexp} and @var{type_regexp} are provided, a function
+is printed only if its name matches @var{regexp} and its type matches
+@var{type_regexp}.
+
+
@kindex info variables
-@item info variables
+@item info variables [-q] [-n]
Print the names and data types of all variables that are defined
outside of functions (i.e.@: excluding local variables).
-
-@item info variables @var{regexp}
-Print the names and data types of all variables (except for local
-variables) whose names contain a match for regular expression
-@var{regexp}.
+The printed variables are grouped by source files and annotated with
+their respective source line numbers.
+
+In programs using different languages, @value{GDBN} chooses the syntax
+to print the variable name and type according to the
+@samp{set language} value: using @samp{set language auto}
+(see @ref{Automatically, ,Set Language Automatically}) means to use the
+language of the variable, other values mean to use
+the manually specified language (see @ref{Manually, ,Set Language Manually}).
+
+The @samp{-n} flag excludes non-debugging symbols from the results.
+
+The optional flag @samp{-q}, which stands for @samp{quiet}, disables
+printing header information and messages explaining why no variables
+have been printed.
+
+@item info variables [-q] [-n] [-t @var{type_regexp}] [@var{regexp}]
+Like @kbd{info variables}, but only print the variables selected
+with the provided regexp(s).
+
+If @var{regexp} is provided, print only the variables whose names
+match the regular expression @var{regexp}.
+
+If @var{type_regexp} is provided, print only the variables whose
+types, as printed by the @code{whatis} command, match
+the regular expression @var{type_regexp}.
+If @var{type_regexp} contains space(s), it should be enclosed in
+quote characters. If needed, use backslash to escape the meaning
+of special characters or quotes.
+
+If both @var{regexp} and @var{type_regexp} are provided, an argument
+is printed only if its name matches @var{regexp} and its type matches
+@var{type_regexp}.
+
+@kindex info modules
+@cindex modules
+@item info modules @r{[}-q@r{]} @r{[}@var{regexp}@r{]}
+List all Fortran modules in the program, or all modules matching the
+optional regular expression @var{regexp}.
+
+The optional flag @samp{-q}, which stands for @samp{quiet}, disables
+printing header information and messages explaining why no modules
+have been printed.
+
+@kindex info module
+@cindex Fortran modules, information about
+@cindex functions and variables by Fortran module
+@cindex module functions and variables
+@item info module functions @r{[}-q@r{]} @r{[}-m @var{module-regexp}@r{]} @r{[}-t @var{type-regexp}@r{]} @r{[}@var{regexp}@r{]}
+@itemx info module variables @r{[}-q@r{]} @r{[}-m @var{module-regexp}@r{]} @r{[}-t @var{type-regexp}@r{]} @r{[}@var{regexp}@r{]}
+List all functions or variables within all Fortran modules. The set
+of functions or variables listed can be limited by providing some or
+all of the optional regular expressions. If @var{module-regexp} is
+provided, then only Fortran modules matching @var{module-regexp} will
+be searched. Only functions or variables whose type matches the
+optional regular expression @var{type-regexp} will be listed. And
+only functions or variables whose name matches the optional regular
+expression @var{regexp} will be listed.
+
+The optional flag @samp{-q}, which stands for @samp{quiet}, disables
+printing header information and messages explaining why no functions
+or variables have been printed.
@kindex info classes
@cindex Objective-C, classes and selectors
Show the current setting of stack unwinding in the functions called by
@value{GDBN}.
+@item set may-call-functions
+@kindex set may-call-functions
+@cindex disabling calling functions in the program
+@cindex calling functions in the program, disabling
+Set permission to call functions in the program.
+This controls whether @value{GDBN} will attempt to call functions in
+the program, such as with expressions in the @code{print} command. It
+defaults to @code{on}.
+
+To call a function in the program, @value{GDBN} has to temporarily
+modify the state of the inferior. This has potentially undesired side
+effects. Also, having @value{GDBN} call nested functions is likely to
+be erroneous and may even crash the program being debugged. You can
+avoid such hazards by forbidding @value{GDBN} from calling functions
+in the program being debugged. If calling functions in the program
+is forbidden, GDB will throw an error when a command (such as printing
+an expression) starts a function call in the program.
+
+@item show may-call-functions
+@kindex show may-call-functions
+Show permission to call functions in the program.
+
@end table
-@cindex weak alias functions
-Sometimes, a function you wish to call is actually a @dfn{weak alias}
-for another function. In such case, @value{GDBN} might not pick up
-the type information, including the types of the function arguments,
-which causes @value{GDBN} to call the inferior function incorrectly.
-As a result, the called function will function erroneously and may
-even crash. A solution to that is to use the name of the aliased
-function instead.
+@subsection Calling functions with no debug info
+
+@cindex no debug info functions
+Sometimes, a function you wish to call is missing debug information.
+In such case, @value{GDBN} does not know the type of the function,
+including the types of the function's parameters. To avoid calling
+the inferior function incorrectly, which could result in the called
+function functioning erroneously and even crash, @value{GDBN} refuses
+to call the function unless you tell it the type of the function.
+
+For prototyped (i.e.@: ANSI/ISO style) functions, there are two ways
+to do that. The simplest is to cast the call to the function's
+declared return type. For example:
+
+@smallexample
+(@value{GDBP}) p getenv ("PATH")
+'getenv' has unknown return type; cast the call to its declared return type
+(@value{GDBP}) p (char *) getenv ("PATH")
+$1 = 0x7fffffffe7ba "/usr/local/bin:/"...
+@end smallexample
+
+Casting the return type of a no-debug function is equivalent to
+casting the function to a pointer to a prototyped function that has a
+prototype that matches the types of the passed-in arguments, and
+calling that. I.e., the call above is equivalent to:
+
+@smallexample
+(@value{GDBP}) p ((char * (*) (const char *)) getenv) ("PATH")
+@end smallexample
+
+@noindent
+and given this prototyped C or C++ function with float parameters:
+
+@smallexample
+float multiply (float v1, float v2) @{ return v1 * v2; @}
+@end smallexample
+
+@noindent
+these calls are equivalent:
+
+@smallexample
+(@value{GDBP}) p (float) multiply (2.0f, 3.0f)
+(@value{GDBP}) p ((float (*) (float, float)) multiply) (2.0f, 3.0f)
+@end smallexample
+
+If the function you wish to call is declared as unprototyped (i.e.@:
+old K&R style), you must use the cast-to-function-pointer syntax, so
+that @value{GDBN} knows that it needs to apply default argument
+promotions (promote float arguments to double). @xref{ABI, float
+promotion}. For example, given this unprototyped C function with
+float parameters, and no debug info:
+
+@smallexample
+float
+multiply_noproto (v1, v2)
+ float v1, v2;
+@{
+ return v1 * v2;
+@}
+@end smallexample
+
+@noindent
+you call it like this:
+
+@smallexample
+ (@value{GDBP}) p ((float (*) ()) multiply_noproto) (2.0f, 3.0f)
+@end smallexample
@node Patching
@section Patching Programs
@end table
@table @code
-@item compile print @var{expr}
-@itemx compile print /@var{f} @var{expr}
+@item compile print [[@var{options}] --] @var{expr}
+@itemx compile print [[@var{options}] --] /@var{f} @var{expr}
Compile and execute @var{expr} with the compiler language found as the
current language in @value{GDBN} (@pxref{Languages}). By default the
value of @var{expr} is printed in a format appropriate to its data type;
you can choose a different format by specifying @samp{/@var{f}}, where
@var{f} is a letter specifying the format; see @ref{Output Formats,,Output
-Formats}.
+Formats}. The @code{compile print} command accepts the same options
+as the @code{print} command; see @ref{print options}.
-@item compile print
-@itemx compile print /@var{f}
+@item compile print [[@var{options}] --]
+@itemx compile print [[@var{options}] --] /@var{f}
@cindex reprint the last value
Alternatively you can enter the expression (source code producing it) as
multiple lines of text. To enter this mode, invoke the @samp{compile print}
@item show debug compile
Displays the current state of displaying @value{GDBN} process of
compiling and injecting the code.
+
+@anchor{set debug compile-cplus-types}
+@item set debug compile-cplus-types
+@cindex compile C@t{++} type conversion
+Turns on or off the display of C@t{++} type conversion debugging information.
+The default is off.
+
+@item show debug compile-cplus-types
+Displays the current state of displaying debugging information for
+C@t{++} type conversion.
@end table
@subsection Compilation options for the @code{compile} command
@subsection Compiler search for the @code{compile} command
-@value{GDBN} needs to find @value{NGCC} for the inferior being debugged which
-may not be obvious for remote targets of different architecture than where
-@value{GDBN} is running. Environment variable @code{PATH} (@code{PATH} from
-shell that executed @value{GDBN}, not the one set by @value{GDBN}
-command @code{set environment}). @xref{Environment}. @code{PATH} on
+@value{GDBN} needs to find @value{NGCC} for the inferior being debugged
+which may not be obvious for remote targets of different architecture
+than where @value{GDBN} is running. Environment variable @code{PATH} on
@value{GDBN} host is searched for @value{NGCC} binary matching the
-target architecture and operating system.
+target architecture and operating system. This search can be overriden
+by @code{set compile-gcc} @value{GDBN} command below. @code{PATH} is
+taken from shell that executed @value{GDBN}, it is not the value set by
+@value{GDBN} command @code{set environment}). @xref{Environment}.
+
Specifically @code{PATH} is searched for binaries matching regular expression
@code{@var{arch}(-[^-]*)?-@var{os}-gcc} according to the inferior target being
for pattern @code{s390x?}. @var{os} is currently supported only for
pattern @code{linux(-gnu)?}.
+On Posix hosts the compiler driver @value{GDBN} needs to find also
+shared library @file{libcc1.so} from the compiler. It is searched in
+default shared library search path (overridable with usual environment
+variable @code{LD_LIBRARY_PATH}), unrelated to @code{PATH} or @code{set
+compile-gcc} settings. Contrary to it @file{libcc1plugin.so} is found
+according to the installation of the found compiler --- as possibly
+specified by the @code{set compile-gcc} command.
+
+@table @code
+@item set compile-gcc
+@cindex compile command driver filename override
+Set compilation command used for compiling and injecting code with the
+@code{compile} commands. If this option is not set (it is set to
+an empty string), the search described above will occur --- that is the
+default.
+
+@item show compile-gcc
+Displays the current compile command @value{NGCC} driver filename.
+If set, it is the main command @command{gcc}, found usually for example
+under name @file{x86_64-linux-gnu-gcc}.
+@end table
+
@node GDB Files
@chapter @value{GDBN} Files
discard information on the executable file.
@kindex symbol-file
-@item symbol-file @r{[} @var{filename} @r{]}
+@item symbol-file @r{[} @var{filename} @r{[} -o @var{offset} @r{]]}
Read symbol table information from file @var{filename}. @code{PATH} is
searched when necessary. Use the @code{file} command to get both symbol
table and program to run from the same file.
+If an optional @var{offset} is specified, it is added to the start
+address of each section in the symbol file. This is useful if the
+program is relocated at runtime, such as the Linux kernel with kASLR
+enabled.
+
@code{symbol-file} with no argument clears out @value{GDBN} information on your
program's symbol table.
load symbol table information, if you want to be sure @value{GDBN} has the
entire symbol table available.
+@cindex @code{-readnever}, option for symbol-file command
+@cindex never read symbols
+@cindex symbols, never read
+@item symbol-file @r{[} -readnever @r{]} @var{filename}
+@itemx file @r{[} -readnever @r{]} @var{filename}
+You can instruct @value{GDBN} to never read the symbolic information
+contained in @var{filename} by using the @samp{-readnever} option.
+@xref{--readnever}.
+
@c FIXME: for now no mention of directories, since this seems to be in
@c flux. 13mar1992 status is that in theory GDB would look either in
@c current dir or in same dir as myprog; but issues like competing
@kindex add-symbol-file
@cindex dynamic linking
-@item add-symbol-file @var{filename} @var{address}
-@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]}
-@itemx add-symbol-file @var{filename} @var{address} -s @var{section} @var{address} @dots{}
+@item add-symbol-file @var{filename} @r{[} -readnow @r{|} -readnever @r{]} @r{[} -o @var{offset} @r{]} @r{[} @var{textaddress} @r{]} @r{[} -s @var{section} @var{address} @dots{} @r{]}
The @code{add-symbol-file} command reads additional symbol table
information from the file @var{filename}. You would use this command
when @var{filename} has been dynamically loaded (by some other means)
-into the program that is running. The @var{address} should give the memory
-address at which the file has been loaded; @value{GDBN} cannot figure
-this out for itself. You can additionally specify an arbitrary number
-of @samp{-s @var{section} @var{address}} pairs, to give an explicit
-section name and base address for that section. You can specify any
-@var{address} as an expression.
+into the program that is running. The @var{textaddress} parameter gives
+the memory address at which the file's text section has been loaded.
+You can additionally specify the base address of other sections using
+an arbitrary number of @samp{-s @var{section} @var{address}} pairs.
+If a section is omitted, @value{GDBN} will use its default addresses
+as found in @var{filename}. Any @var{address} or @var{textaddress}
+can be given as an expression.
+
+If an optional @var{offset} is specified, it is added to the start
+address of each section, except those for which the address was
+specified explicitly.
The symbol table of the file @var{filename} is added to the symbol table
originally read with the @code{symbol-file} command. You can use the
only on some operating systems, when using the ELF or PE file formats
for binary files and the @sc{gnu} Binutils.) For more details about
this feature, see the description of the @option{--build-id}
-command-line option in @ref{Options, , Command Line Options, ld.info,
+command-line option in @ref{Options, , Command Line Options, ld,
The GNU Linker}. The debug info file's name is not specified
explicitly by the build ID, but can be computed from the build ID, see
below.
@item
For the ``debug link'' method, @value{GDBN} looks up the named file in
the directory of the executable file, then in a subdirectory of that
-directory named @file{.debug}, and finally under each one of the global debug
-directories, in a subdirectory whose name is identical to the leading
-directories of the executable's absolute file name.
+directory named @file{.debug}, and finally under each one of the
+global debug directories, in a subdirectory whose name is identical to
+the leading directories of the executable's absolute file name. (On
+MS-Windows/MS-DOS, the drive letter of the executable's leading
+directories is converted to a one-letter subdirectory, i.e.@:
+@file{d:/usr/bin/} is converted to @file{/d/usr/bin/}, because Windows
+filesystems disallow colons in file names.)
@item
For the ``build ID'' method, @value{GDBN} looks in the
@value{GDBN} provides a way to build an index, which speeds up
startup.
+For convenience, @value{GDBN} comes with a program,
+@command{gdb-add-index}, which can be used to add the index to a
+symbol file. It takes the symbol file as its only argument:
+
+@smallexample
+$ gdb-add-index symfile
+@end smallexample
+
+@xref{gdb-add-index}.
+
+It is also possible to do the work manually. Here is what
+@command{gdb-add-index} does behind the curtains.
+
The index is stored as a section in the symbol file. @value{GDBN} can
write the index to a file, then you can put it into the symbol file
using @command{objcopy}.
To create an index file, use the @code{save gdb-index} command:
@table @code
-@item save gdb-index @var{directory}
+@item save gdb-index [-dwarf-5] @var{directory}
@kindex save gdb-index
-Create an index file for each symbol file currently known by
-@value{GDBN}. Each file is named after its corresponding symbol file,
-with @samp{.gdb-index} appended, and is written into the given
-@var{directory}.
+Create index files for all symbol files currently known by
+@value{GDBN}. For each known @var{symbol-file}, this command by
+default creates it produces a single file
+@file{@var{symbol-file}.gdb-index}. If you invoke this command with
+the @option{-dwarf-5} option, it produces 2 files:
+@file{@var{symbol-file}.debug_names} and
+@file{@var{symbol-file}.debug_str}. The files are created in the
+given @var{directory}.
@end table
Once you have created an index file you can merge it into your symbol
--set-section-flags .gdb_index=readonly symfile symfile
@end smallexample
+Or for @code{-dwarf-5}:
+
+@smallexample
+$ objcopy --dump-section .debug_str=symfile.debug_str.new symfile
+$ cat symfile.debug_str >>symfile.debug_str.new
+$ objcopy --add-section .debug_names=symfile.gdb-index \
+ --set-section-flags .debug_names=readonly \
+ --update-section .debug_str=symfile.debug_str.new symfile symfile
+@end smallexample
+
@value{GDBN} will normally ignore older versions of @file{.gdb_index}
sections that have been deprecated. Usually they are deprecated because
they are missing a new feature or have performance issues.
@end smallexample
There are currently some limitation on indices. They only work when
-for DWARF debugging information, not stabs. And, they do not
-currently work for programs using Ada.
+using DWARF debugging information, not stabs. And, only the
+@code{-dwarf-5} index works for programs using Ada.
+
+@subsection Automatic symbol index cache
+
+@cindex automatic symbol index cache
+It is possible for @value{GDBN} to automatically save a copy of this index in a
+cache on disk and retrieve it from there when loading the same binary in the
+future. This feature can be turned on with @kbd{set index-cache on}. The
+following commands can be used to tweak the behavior of the index cache.
+
+@table @code
+
+@kindex set index-cache
+@item set index-cache on
+@itemx set index-cache off
+Enable or disable the use of the symbol index cache.
+
+@item set index-cache directory @var{directory}
+@kindex show index-cache
+@itemx show index-cache directory
+Set/show the directory where index files will be saved.
+
+The default value for this directory depends on the host platform. On
+most systems, the index is cached in the @file{gdb} subdirectory of
+the directory pointed to by the @env{XDG_CACHE_HOME} environment
+variable, if it is defined, else in the @file{.cache/gdb} subdirectory
+of your home directory. However, on some systems, the default may
+differ according to local convention.
+
+There is no limit on the disk space used by index cache. It is perfectly safe
+to delete the content of that directory to free up disk space.
+
+@item show index-cache stats
+Print the number of cache hits and misses since the launch of @value{GDBN}.
+
+@end table
@node Symbol Errors
@section Errors Reading Symbol Files
@table @code
-@kindex load @var{filename}
-@item load @var{filename}
+@kindex load @var{filename} @var{offset}
+@item load @var{filename} @var{offset}
@anchor{load}
Depending on what remote debugging facilities are configured into
@value{GDBN}, the @code{load} command may be available. Where it exists, it
specifies a fixed address.
@c FIXME! This would be a good place for an xref to the GNU linker doc.
+It is also possible to tell @value{GDBN} to load the executable file at a
+specific offset described by the optional argument @var{offset}. When
+@var{offset} is provided, @var{filename} must also be provided.
+
Depending on the remote side capabilities, @value{GDBN} may be able to
load programs into flash memory.
@end table
+If the @code{set endian auto} mode is in effect and no executable has
+been selected, then the endianness used is the last one chosen either
+by one of the @code{set endian big} and @code{set endian little}
+commands or by inferring from the last executable used. If no
+endianness has been previously chosen, then the default for this mode
+is inferred from the target @value{GDBN} has been built for, and is
+@code{little} if the name of the target CPU has an @code{el} suffix
+and @code{big} otherwise.
+
Note that these commands merely adjust interpretation of symbolic
data on the host, and that they have absolutely no effect on the
target system.
@subsection Remote Connection Commands
@cindex remote connection commands
-@value{GDBN} can communicate with the target over a serial line, or
+@value{GDBN} can communicate with the target over a serial line, a
+local Unix domain socket, or
over an @acronym{IP} network using @acronym{TCP} or @acronym{UDP}. In
each case, @value{GDBN} uses the same protocol for debugging your
program; only the medium carrying the debugging packets varies. The
(@pxref{Remote Configuration, set serial baud}) before the
@code{target} command.
+@item target remote @var{local-socket}
+@itemx target extended-remote @var{local-socket}
+@cindex local socket, @code{target remote}
+@cindex Unix domain socket
+Use @var{local-socket} to communicate with the target. For example,
+to use a local Unix domain socket bound to the file system entry @file{/tmp/gdb-socket0}:
+
+@smallexample
+target remote /tmp/gdb-socket0
+@end smallexample
+
+Note that this command has the same form as the command to connect
+to a serial line. @value{GDBN} will automatically determine which
+kind of file you have specified and will make the appropriate kind
+of connection.
+This feature is not available if the host system does not support
+Unix domain sockets.
+
@item target remote @code{@var{host}:@var{port}}
+@itemx target remote @code{@var{[host]}:@var{port}}
@itemx target remote @code{tcp:@var{host}:@var{port}}
+@itemx target remote @code{tcp:@var{[host]}:@var{port}}
+@itemx target remote @code{tcp4:@var{host}:@var{port}}
+@itemx target remote @code{tcp6:@var{host}:@var{port}}
+@itemx target remote @code{tcp6:@var{[host]}:@var{port}}
@itemx target extended-remote @code{@var{host}:@var{port}}
+@itemx target extended-remote @code{@var{[host]}:@var{port}}
@itemx target extended-remote @code{tcp:@var{host}:@var{port}}
+@itemx target extended-remote @code{tcp:@var{[host]}:@var{port}}
+@itemx target extended-remote @code{tcp4:@var{host}:@var{port}}
+@itemx target extended-remote @code{tcp6:@var{host}:@var{port}}
+@itemx target extended-remote @code{tcp6:@var{[host]}:@var{port}}
@cindex @acronym{TCP} port, @code{target remote}
Debug using a @acronym{TCP} connection to @var{port} on @var{host}.
-The @var{host} may be either a host name or a numeric @acronym{IP}
-address; @var{port} must be a decimal number. The @var{host} could be
-the target machine itself, if it is directly connected to the net, or
-it might be a terminal server which in turn has a serial line to the
-target.
+The @var{host} may be either a host name, a numeric @acronym{IPv4}
+address, or a numeric @acronym{IPv6} address (with or without the
+square brackets to separate the address from the port); @var{port}
+must be a decimal number. The @var{host} could be the target machine
+itself, if it is directly connected to the net, or it might be a
+terminal server which in turn has a serial line to the target.
For example, to connect to port 2828 on a terminal server named
@code{manyfarms}:
target remote manyfarms:2828
@end smallexample
+To connect to port 2828 on a terminal server whose address is
+@code{2001:0db8:85a3:0000:0000:8a2e:0370:7334}, you can either use the
+square bracket syntax:
+
+@smallexample
+target remote [2001:0db8:85a3:0000:0000:8a2e:0370:7334]:2828
+@end smallexample
+
+@noindent
+or explicitly specify the @acronym{IPv6} protocol:
+
+@smallexample
+target remote tcp6:2001:0db8:85a3:0000:0000:8a2e:0370:7334:2828
+@end smallexample
+
+This last example may be confusing to the reader, because there is no
+visible separation between the hostname and the port number.
+Therefore, we recommend the user to provide @acronym{IPv6} addresses
+using square brackets for clarity. However, it is important to
+mention that for @value{GDBN} there is no ambiguity: the number after
+the last colon is considered to be the port number.
+
If your remote target is actually running on the same machine as your
debugger session (e.g.@: a simulator for your target running on the
same host), you can omit the hostname. For example, to connect to
Note that the colon is still required here.
@item target remote @code{udp:@var{host}:@var{port}}
+@itemx target remote @code{udp:@var{[host]}:@var{port}}
+@itemx target remote @code{udp4:@var{host}:@var{port}}
+@itemx target remote @code{udp6:@var{[host]}:@var{port}}
@itemx target extended-remote @code{udp:@var{host}:@var{port}}
+@itemx target extended-remote @code{udp:@var{host}:@var{port}}
+@itemx target extended-remote @code{udp:@var{[host]}:@var{port}}
+@itemx target extended-remote @code{udp4:@var{host}:@var{port}}
+@itemx target extended-remote @code{udp6:@var{host}:@var{port}}
+@itemx target extended-remote @code{udp6:@var{[host]}:@var{port}}
@cindex @acronym{UDP} port, @code{target remote}
Debug using @acronym{UDP} packets to @var{port} on @var{host}. For example, to
connect to @acronym{UDP} port 2828 on a terminal server named @code{manyfarms}:
status information about the debugging process.
@cindex @option{--remote-debug}, @code{gdbserver} option
The @option{--remote-debug} option tells @code{gdbserver} to display
-remote protocol debug output. These options are intended for
-@code{gdbserver} development and for bug reports to the developers.
+remote protocol debug output.
+@cindex @option{--debug-file}, @code{gdbserver} option
+@cindex @code{gdbserver}, send all debug output to a single file
+The @option{--debug-file=@var{filename}} option tells @code{gdbserver} to
+write any debug output to the given @var{filename}. These options are intended
+for @code{gdbserver} development and for bug reports to the developers.
@cindex @option{--debug-format}, @code{gdbserver} option
The @option{--debug-format=option1[,option2,...]} option tells
$ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog
@end smallexample
+@cindex @option{--selftest}
+The @option{--selftest} option runs the self tests in @code{gdbserver}:
+
+@smallexample
+$ gdbserver --selftest
+Ran 2 unit tests, 0 failed
+@end smallexample
+
+These tests are disabled in release.
@subsection Connecting to @code{gdbserver}
The basic procedure for connecting to the remote target is:
Disable or enable specific debugging messages associated with the remote
protocol (@pxref{Remote Protocol}).
+@item monitor set debug-file filename
+@itemx monitor set debug-file
+Send any debug output to the given file, or to stderr.
+
@item monitor set debug-format option1@r{[},option2,...@r{]}
Specify additional text to add to debugging messages.
Possible options are:
Record remote serial communications on the named @var{file}. The
default is not to record at all.
-@item show remotelogfile.
+@item show remotelogfile
Show the current setting of the file name on which to record the
serial communications.
@anchor{set remote hardware-breakpoint-limit}
@item set remote hardware-watchpoint-limit @var{limit}
@itemx set remote hardware-breakpoint-limit @var{limit}
-Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or
-watchpoints. A limit of -1, the default, is treated as unlimited.
+Restrict @value{GDBN} to using @var{limit} remote hardware watchpoints
+or breakpoints. The @var{limit} can be set to 0 to disable hardware
+watchpoints or breakpoints, and @code{unlimited} for unlimited
+watchpoints or breakpoints.
+
+@item show remote hardware-watchpoint-limit
+@itemx show remote hardware-breakpoint-limit
+Show the current limit for the number of hardware watchpoints or
+breakpoints that @value{GDBN} can use.
@cindex limit hardware watchpoints length
@cindex remote target, limit watchpoints length
@anchor{set remote hardware-watchpoint-length-limit}
@item set remote hardware-watchpoint-length-limit @var{limit}
-Restrict @value{GDBN} to using @var{limit} bytes for the maximum length of
-a remote hardware watchpoint. A limit of -1, the default, is treated
-as unlimited.
+Restrict @value{GDBN} to using @var{limit} bytes for the maximum
+length of a remote hardware watchpoint. A @var{limit} of 0 disables
+hardware watchpoints and @code{unlimited} allows watchpoints of any
+length.
@item show remote hardware-watchpoint-length-limit
Show the current limit (in bytes) of the maximum length of
@tab @code{qXfer:sdata:read}
@tab @code{print $_sdata}
-@item @code{read-spu-object}
-@tab @code{qXfer:spu:read}
-@tab @code{info spu}
-
-@item @code{write-spu-object}
-@tab @code{qXfer:spu:write}
-@tab @code{info spu}
-
@item @code{read-siginfo-object}
@tab @code{qXfer:siginfo:read}
@tab @code{print $_siginfo}
@tab @code{QDisableRandomization}
@tab @code{set disable-randomization}
+@item @code{startup-with-shell}
+@tab @code{QStartupWithShell}
+@tab @code{set startup-with-shell}
+
+@item @code{environment-hex-encoded}
+@tab @code{QEnvironmentHexEncoded}
+@tab @code{set environment}
+
+@item @code{environment-unset}
+@tab @code{QEnvironmentUnset}
+@tab @code{unset environment}
+
+@item @code{environment-reset}
+@tab @code{QEnvironmentReset}
+@tab @code{Reset the inferior environment (i.e., unset user-set variables)}
+
+@item @code{set-working-dir}
+@tab @code{QSetWorkingDir}
+@tab @code{set cwd}
+
@item @code{conditional-breakpoints-packet}
@tab @code{Z0 and Z1}
@tab @code{Support for target-side breakpoint condition evaluation}
@menu
* BSD libkvm Interface:: Debugging BSD kernel memory images
-* SVR4 Process Information:: SVR4 process information
+* Process Information:: Process information
* DJGPP Native:: Features specific to the DJGPP port
* Cygwin Native:: Features specific to the Cygwin port
* Hurd Native:: Features specific to @sc{gnu} Hurd
* Darwin:: Features specific to Darwin
+* FreeBSD:: Features specific to FreeBSD
@end menu
@node BSD libkvm Interface
modern FreeBSD systems.
@end table
-@node SVR4 Process Information
-@subsection SVR4 Process Information
+@node Process Information
+@subsection Process Information
@cindex /proc
@cindex examine process image
@cindex process info via @file{/proc}
-Many versions of SVR4 and compatible systems provide a facility called
-@samp{/proc} that can be used to examine the image of a running
-process using file-system subroutines.
+Some operating systems provide interfaces to fetch additional
+information about running processes beyond memory and per-thread
+register state. If @value{GDBN} is configured for an operating system
+with a supported interface, the command @code{info proc} is available
+to report information about the process running your program, or about
+any process running on your system.
+
+One supported interface is a facility called @samp{/proc} that can be
+used to examine the image of a running process using file-system
+subroutines. This facility is supported on @sc{gnu}/Linux and Solaris
+systems.
-If @value{GDBN} is configured for an operating system with this
-facility, the command @code{info proc} is available to report
-information about the process running your program, or about any
-process running on your system. This includes, as of this writing,
-@sc{gnu}/Linux and Solaris, for example.
+On FreeBSD systems, system control nodes are used to query process
+information.
-This command may also work on core files that were created on a system
-that has the @samp{/proc} facility.
+In addition, some systems may provide additional process information
+in core files. Note that a core file may include a subset of the
+information available from a live process. Process information is
+currently avaiable from cores created on @sc{gnu}/Linux and FreeBSD
+systems.
@table @code
@kindex info proc
@cindex process ID
@item info proc
@itemx info proc @var{process-id}
-Summarize available information about any running process. If a
+Summarize available information about a process. If a
process ID is specified by @var{process-id}, display information about
that process; otherwise display information about the program being
debugged. The summary includes the debugged process ID, the command
@item info proc cmdline
@cindex info proc cmdline
Show the original command line of the process. This command is
-specific to @sc{gnu}/Linux.
+supported on @sc{gnu}/Linux and FreeBSD.
@item info proc cwd
@cindex info proc cwd
Show the current working directory of the process. This command is
-specific to @sc{gnu}/Linux.
+supported on @sc{gnu}/Linux and FreeBSD.
@item info proc exe
@cindex info proc exe
-Show the name of executable of the process. This command is specific
-to @sc{gnu}/Linux.
+Show the name of executable of the process. This command is supported
+on @sc{gnu}/Linux and FreeBSD.
+
+@item info proc files
+@cindex info proc files
+Show the file descriptors open by the process. For each open file
+descriptor, @value{GDBN} shows its number, type (file, directory,
+character device, socket), file pointer offset, and the name of the
+resource open on the descriptor. The resource name can be a file name
+(for files, directories, and devices) or a protocol followed by socket
+address (for network connections). This command is supported on
+FreeBSD.
+
+This example shows the open file descriptors for a process using a
+tty for standard input and output as well as two network sockets:
+
+@smallexample
+(gdb) info proc files 22136
+process 22136
+Open files:
+
+ FD Type Offset Flags Name
+ text file - r-------- /usr/bin/ssh
+ ctty chr - rw------- /dev/pts/20
+ cwd dir - r-------- /usr/home/john
+ root dir - r-------- /
+ 0 chr 0x32933a4 rw------- /dev/pts/20
+ 1 chr 0x32933a4 rw------- /dev/pts/20
+ 2 chr 0x32933a4 rw------- /dev/pts/20
+ 3 socket 0x0 rw----n-- tcp4 10.0.1.2:53014 -> 10.0.1.10:22
+ 4 socket 0x0 rw------- unix stream:/tmp/ssh-FIt89oAzOn5f/agent.2456
+@end smallexample
@item info proc mappings
@cindex memory address space mappings
-Report the memory address space ranges accessible in the program, with
-information on whether the process has read, write, or execute access
-rights to each range. On @sc{gnu}/Linux systems, each memory range
-includes the object file which is mapped to that range, instead of the
-memory access rights to that range.
+Report the memory address space ranges accessible in a process. On
+Solaris and FreeBSD systems, each memory range includes information on
+whether the process has read, write, or execute access rights to each
+range. On @sc{gnu}/Linux and FreeBSD systems, each memory range
+includes the object file which is mapped to that range.
@item info proc stat
@itemx info proc status
@cindex process detailed status information
-These subcommands are specific to @sc{gnu}/Linux systems. They show
-the process-related information, including the user ID and group ID;
-how many threads are there in the process; its virtual memory usage;
-the signals that are pending, blocked, and ignored; its TTY; its
-consumption of system and user time; its stack size; its @samp{nice}
-value; etc. For more information, see the @samp{proc} man page
-(type @kbd{man 5 proc} from your shell prompt).
+Show additional process-related information, including the user ID and
+group ID; virtual memory usage; the signals that are pending, blocked,
+and ignored; its TTY; its consumption of system and user time; its
+stack size; its @samp{nice} value; etc. These commands are supported
+on @sc{gnu}/Linux and FreeBSD.
+
+For @sc{gnu}/Linux systems, see the @samp{proc} man page for more
+information (type @kbd{man 5 proc} from your shell prompt).
+
+For FreeBSD systems, @code{info proc stat} is an alias for @code{info
+proc status}.
@item info proc all
Show all the information about the process described under all of the
@smallexample
(@value{GDBP}) print 'cygwin1!__argv'
-$1 = 268572168
+'cygwin1!__argv' has unknown type; cast it to its declared type
@end smallexample
@smallexample
(@value{GDBP}) x 'cygwin1!__argv'
-0x10021610: "\230y\""
+'cygwin1!__argv' has unknown type; cast it to its declared type
@end smallexample
And two possible solutions:
Show the current state of exceptions trapping.
@end table
+@node FreeBSD
+@subsection FreeBSD
+@cindex FreeBSD
+
+When the ABI of a system call is changed in the FreeBSD kernel, this
+is implemented by leaving a compatibility system call using the old
+ABI at the existing number and allocating a new system call number for
+the version using the new ABI. As a convenience, when a system call
+is caught by name (@pxref{catch syscall}), compatibility system calls
+are also caught.
+
+For example, FreeBSD 12 introduced a new variant of the @code{kevent}
+system call and catching the @code{kevent} system call by name catches
+both variants:
+
+@smallexample
+(@value{GDBP}) catch syscall kevent
+Catchpoint 1 (syscalls 'freebsd11_kevent' [363] 'kevent' [560])
+(@value{GDBP})
+@end smallexample
+
@node Embedded OS
@section Embedded Operating Systems
* M68K:: Motorola M68K
* MicroBlaze:: Xilinx MicroBlaze
* MIPS Embedded:: MIPS Embedded
+* OpenRISC 1000:: OpenRISC 1000 (or1k)
* PowerPC Embedded:: PowerPC Embedded
* AVR:: Atmel AVR
* CRIS:: CRIS
@item set debug arc
@kindex set debug arc
Control the level of ARC specific debug messages. Use 0 for no messages (the
-default) and 1 for debug messages. At present higher values offer no further
-messages.
+default), 1 for debug messages, and 2 for even more debug messages.
@item show debug arc
@kindex show debug arc
Show the level of ARC specific debugging in operation.
+@item maint print arc arc-instruction @var{address}
+@kindex maint print arc arc-instruction
+Print internal disassembler information about instruction at a given address.
+
@end table
@node ARM
@samp{show mipsfpu}.
@end table
+@node OpenRISC 1000
+@subsection OpenRISC 1000
+@cindex OpenRISC 1000
+
+@noindent
+The OpenRISC 1000 provides a free RISC instruction set architecture. It is
+mainly provided as a soft-core which can run on Xilinx, Altera and other
+FPGA's.
+
+@value{GDBN} for OpenRISC supports the below commands when connecting to
+a target:
+
+@table @code
+
+@kindex target sim
+@item target sim
+
+Runs the builtin CPU simulator which can run very basic
+programs but does not support most hardware functions like MMU.
+For more complex use cases the user is advised to run an external
+target, and connect using @samp{target remote}.
+
+Example: @code{target sim}
+
+@item set debug or1k
+Toggle whether to display OpenRISC-specific debugging messages from the
+OpenRISC target support subsystem.
+
+@item show debug or1k
+Show whether OpenRISC-specific debugging messages are enabled.
+@end table
+
@node PowerPC Embedded
@subsection PowerPC Embedded
* Alpha::
* MIPS::
* HPPA:: HP PA architecture
-* SPU:: Cell Broadband Engine SPU architecture
* PowerPC::
* Nios II::
+* Sparc64::
+* S12Z::
@end menu
@node AArch64
@end table
+@subsubsection AArch64 SVE.
+@cindex AArch64 SVE.
+
+When @value{GDBN} is debugging the AArch64 architecture, if the Scalable Vector
+Extension (SVE) is present, then @value{GDBN} will provide the vector registers
+@code{$z0} through @code{$z31}, vector predicate registers @code{$p0} through
+@code{$p15}, and the @code{$ffr} register. In addition, the pseudo register
+@code{$vg} will be provided. This is the vector granule for the current thread
+and represents the number of 64-bit chunks in an SVE @code{z} register.
+
+If the vector length changes, then the @code{$vg} register will be updated,
+but the lengths of the @code{z} and @code{p} registers will not change. This
+is a known limitation of @value{GDBN} and does not affect the execution of the
+target process.
+
+@subsubsection AArch64 Pointer Authentication.
+@cindex AArch64 Pointer Authentication.
+
+When @value{GDBN} is debugging the AArch64 architecture, and the program is
+using the v8.3-A feature Pointer Authentication (PAC), then whenever the link
+register @code{$lr} is pointing to an PAC function its value will be masked.
+When GDB prints a backtrace, any addresses that required unmasking will be
+postfixed with the marker [PAC]. When using the MI, this is printed as part
+of the @code{addr_flags} field.
+
@node i386
@subsection x86 Architecture-specific Issues
for lower and upper bounds respectively.
@end table
+When you call an inferior function on an Intel MPX enabled program,
+GDB sets the inferior's bound registers to the init (disabled) state
+before calling the function. As a consequence, bounds checks for the
+pointer arguments passed to the function will always pass.
+
+This is necessary because when you call an inferior function, the
+program is usually in the middle of the execution of other function.
+Since at that point bound registers are in an arbitrary state, not
+clearing them would lead to random bound violations in the called
+function.
+
+You can still examine the influence of the bound registers on the
+execution of the called function by stopping the execution of the
+called function at its prologue, setting bound registers, and
+continuing the execution. For example:
+
+@smallexample
+ $ break *upper
+ Breakpoint 2 at 0x4009de: file i386-mpx-call.c, line 47.
+ $ print upper (a, b, c, d, 1)
+ Breakpoint 2, upper (a=0x0, b=0x6e0000005b, c=0x0, d=0x0, len=48)....
+ $ print $bnd0
+ @{lbound = 0x0, ubound = ffffffff@} : size -1
+@end smallexample
+
+At this last step the value of bnd0 can be changed for investigation of bound
+violations caused along the execution of the call. In order to know how to
+set the bound registers or bound table for the call consult the ABI.
+
@node Alpha
@subsection Alpha
@end table
-@node SPU
-@subsection Cell Broadband Engine SPU architecture
-@cindex Cell Broadband Engine
-@cindex SPU
-
-When @value{GDBN} is debugging the Cell Broadband Engine SPU architecture,
-it provides the following special commands:
-
-@table @code
-@item info spu event
-@kindex info spu
-Display SPU event facility status. Shows current event mask
-and pending event status.
-
-@item info spu signal
-Display SPU signal notification facility status. Shows pending
-signal-control word and signal notification mode of both signal
-notification channels.
-
-@item info spu mailbox
-Display SPU mailbox facility status. Shows all pending entries,
-in order of processing, in each of the SPU Write Outbound,
-SPU Write Outbound Interrupt, and SPU Read Inbound mailboxes.
-
-@item info spu dma
-Display MFC DMA status. Shows all pending commands in the MFC
-DMA queue. For each entry, opcode, tag, class IDs, effective
-and local store addresses and transfer size are shown.
-
-@item info spu proxydma
-Display MFC Proxy-DMA status. Shows all pending commands in the MFC
-Proxy-DMA queue. For each entry, opcode, tag, class IDs, effective
-and local store addresses and transfer size are shown.
-
-@end table
-
-When @value{GDBN} is debugging a combined PowerPC/SPU application
-on the Cell Broadband Engine, it provides in addition the following
-special commands:
-
-@table @code
-@item set spu stop-on-load @var{arg}
-@kindex set spu
-Set whether to stop for new SPE threads. When set to @code{on}, @value{GDBN}
-will give control to the user when a new SPE thread enters its @code{main}
-function. The default is @code{off}.
-
-@item show spu stop-on-load
-@kindex show spu
-Show whether to stop for new SPE threads.
-
-@item set spu auto-flush-cache @var{arg}
-Set whether to automatically flush the software-managed cache. When set to
-@code{on}, @value{GDBN} will automatically cause the SPE software-managed
-cache to be flushed whenever SPE execution stops. This provides a consistent
-view of PowerPC memory that is accessed via the cache. If an application
-does not use the software-managed cache, this option has no effect.
-
-@item show spu auto-flush-cache
-Show whether to automatically flush the software-managed cache.
-
-@end table
-
@node PowerPC
@subsection PowerPC
@cindex PowerPC architecture
Show the current setting of Nios II debugging messages.
@end table
+@node Sparc64
+@subsection Sparc64
+@cindex Sparc64 support
+@cindex Application Data Integrity
+@subsubsection ADI Support
+
+The M7 processor supports an Application Data Integrity (ADI) feature that
+detects invalid data accesses. When software allocates memory and enables
+ADI on the allocated memory, it chooses a 4-bit version number, sets the
+version in the upper 4 bits of the 64-bit pointer to that data, and stores
+the 4-bit version in every cacheline of that data. Hardware saves the latter
+in spare bits in the cache and memory hierarchy. On each load and store,
+the processor compares the upper 4 VA (virtual address) bits to the
+cacheline's version. If there is a mismatch, the processor generates a
+version mismatch trap which can be either precise or disrupting. The trap
+is an error condition which the kernel delivers to the process as a SIGSEGV
+signal.
+
+Note that only 64-bit applications can use ADI and need to be built with
+ADI-enabled.
+
+Values of the ADI version tags, which are in granularity of a
+cacheline (64 bytes), can be viewed or modified.
+
+
+@table @code
+@kindex adi examine
+@item adi (examine | x) [ / @var{n} ] @var{addr}
+
+The @code{adi examine} command displays the value of one ADI version tag per
+cacheline.
+
+@var{n} is a decimal integer specifying the number in bytes; the default
+is 1. It specifies how much ADI version information, at the ratio of 1:ADI
+block size, to display.
+
+@var{addr} is the address in user address space where you want @value{GDBN}
+to begin displaying the ADI version tags.
+
+Below is an example of displaying ADI versions of variable "shmaddr".
+
+@smallexample
+(@value{GDBP}) adi x/100 shmaddr
+ 0xfff800010002c000: 0 0
+@end smallexample
+
+@kindex adi assign
+@item adi (assign | a) [ / @var{n} ] @var{addr} = @var{tag}
+
+The @code{adi assign} command is used to assign new ADI version tag
+to an address.
+
+@var{n} is a decimal integer specifying the number in bytes;
+the default is 1. It specifies how much ADI version information, at the
+ratio of 1:ADI block size, to modify.
+
+@var{addr} is the address in user address space where you want @value{GDBN}
+to begin modifying the ADI version tags.
+
+@var{tag} is the new ADI version tag.
+
+For example, do the following to modify then verify ADI versions of
+variable "shmaddr":
+
+@smallexample
+(@value{GDBP}) adi a/100 shmaddr = 7
+(@value{GDBP}) adi x/100 shmaddr
+ 0xfff800010002c000: 7 7
+@end smallexample
+
+@end table
+
+@node S12Z
+@subsection S12Z
+@cindex S12Z support
+
+When @value{GDBN} is debugging the S12Z architecture,
+it provides the following special command:
+
+@table @code
+@item maint info bdccsr
+@kindex maint info bdccsr@r{, S12Z}
+This command displays the current value of the microprocessor's
+BDCCSR register.
+@end table
+
+
@node Controlling GDB
@chapter Controlling @value{GDBN}
* Editing:: Command editing
* Command History:: Command history
* Screen Size:: Screen size
+* Output Styling:: Output styling
* Numbers:: Numbers
* ABI:: Configuring the current ABI
* Auto-loading:: Automatically loading associated files
interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are
encouraged to read that chapter.
+@cindex Readline application name
+@value{GDBN} sets the Readline application name to @samp{gdb}. This
+is useful for conditions in @file{.inputrc}.
+
@node Command History
@section Command History
@cindex command history
Certain commands to @value{GDBN} may produce large amounts of
information output to the screen. To help you read all of it,
@value{GDBN} pauses and asks you for input at the end of each page of
-output. Type @key{RET} when you want to continue the output, or @kbd{q}
-to discard the remaining output. Also, the screen width setting
-determines when to wrap lines of output. Depending on what is being
-printed, @value{GDBN} tries to break the line at a readable place,
-rather than simply letting it overflow onto the following line.
+output. Type @key{RET} when you want to see one more page of output,
+@kbd{q} to discard the remaining output, or @kbd{c} to continue
+without paging for the rest of the current command. Also, the screen
+width setting determines when to wrap lines of output. Depending on
+what is being printed, @value{GDBN} tries to break the line at a
+readable place, rather than simply letting it overflow onto the
+following line.
Normally @value{GDBN} knows the size of the screen from the terminal
driver software. For example, on Unix @value{GDBN} uses the termcap data base
Show the current pagination mode.
@end table
+@node Output Styling
+@section Output Styling
+@cindex styling
+@cindex colors
+
+@kindex set style
+@kindex show style
+@value{GDBN} can style its output on a capable terminal. This is
+enabled by default on most systems, but disabled by default when in
+batch mode (@pxref{Mode Options}). Various style settings are available;
+and styles can also be disabled entirely.
+
+@table @code
+@item set style enabled @samp{on|off}
+Enable or disable all styling. The default is host-dependent, with
+most hosts defaulting to @samp{on}.
+
+@item show style enabled
+Show the current state of styling.
+
+@item set style sources @samp{on|off}
+Enable or disable source code styling. This affects whether source
+code, such as the output of the @code{list} command, is styled. Note
+that source styling only works if styling in general is enabled, and
+if @value{GDBN} was linked with the GNU Source Highlight library. The
+default is @samp{on}.
+
+@item show style sources
+Show the current state of source code styling.
+@end table
+
+Subcommands of @code{set style} control specific forms of styling.
+These subcommands all follow the same pattern: each style-able object
+can be styled with a foreground color, a background color, and an
+intensity.
+
+For example, the style of file names can be controlled using the
+@code{set style filename} group of commands:
+
+@table @code
+@item set style filename background @var{color}
+Set the background to @var{color}. Valid colors are @samp{none}
+(meaning the terminal's default color), @samp{black}, @samp{red},
+@samp{green}, @samp{yellow}, @samp{blue}, @samp{magenta}, @samp{cyan},
+and@samp{white}.
+
+@item set style filename foreground @var{color}
+Set the foreground to @var{color}. Valid colors are @samp{none}
+(meaning the terminal's default color), @samp{black}, @samp{red},
+@samp{green}, @samp{yellow}, @samp{blue}, @samp{magenta}, @samp{cyan},
+and@samp{white}.
+
+@item set style filename intensity @var{value}
+Set the intensity to @var{value}. Valid intensities are @samp{normal}
+(the default), @samp{bold}, and @samp{dim}.
+@end table
+
+The @code{show style} command and its subcommands are styling
+a style name in their output using its own style.
+So, use @command{show style} to see the complete list of styles,
+their characteristics and the visual aspect of each style.
+
+The style-able objects are:
+@table @code
+@item filename
+Control the styling of file names. By default, this style's
+foreground color is green.
+
+@item function
+Control the styling of function names. These are managed with the
+@code{set style function} family of commands. By default, this
+style's foreground color is yellow.
+
+@item variable
+Control the styling of variable names. These are managed with the
+@code{set style variable} family of commands. By default, this style's
+foreground color is cyan.
+
+@item address
+Control the styling of addresses. These are managed with the
+@code{set style address} family of commands. By default, this style's
+foreground color is blue.
+
+@item title
+Control the styling of titles. These are managed with the
+@code{set style title} family of commands. By default, this style's
+intensity is bold. Commands are using the title style to improve
+the readibility of large output. For example, the commands
+@command{apropos} and @command{help} are using the title style
+for the command names.
+
+@item highlight
+Control the styling of highlightings. These are managed with the
+@code{set style highlight} family of commands. By default, this style's
+foreground color is red. Commands are using the highlight style to draw
+the user attention to some specific parts of their output. For example,
+the command @command{apropos -v REGEXP} uses the highlight style to
+mark the documentation parts matching @var{regexp}.
+
+@end table
+
@node Numbers
@section Numbers
@cindex number representation
Turns on or off debugging messages from the FreeBSD LWP debug support.
@item show debug fbsd-lwp
Show the current state of FreeBSD LWP debugging messages.
+@item set debug fbsd-nat
+@cindex FreeBSD native target debug messages
+Turns on or off debugging messages from the FreeBSD native target.
+@item show debug fbsd-nat
+Show the current state of FreeBSD native target debugging messages.
@item set debug frame
@cindex frame debugging info
Turns on or off display of @value{GDBN} frame debugging info. The
@value{GDBN} standard output stream. The default is off.
@item show debug remote
Displays the state of display of remote packets.
+
+@item set debug separate-debug-file
+Turns on or off display of debug output about separate debug file search.
+@item show debug separate-debug-file
+Displays the state of separate debug file search debug output.
+
@item set debug serial
Turns on or off display of @value{GDBN} serial debugging info. The
default is off.
@end table
+@ifset SYSTEM_GDBINIT_DIR
+This setting is not used for files in the system-wide gdbinit directory.
+Files in that directory must have an extension matching their language,
+or have a @file{.gdb} extension to be interpreted as regular @value{GDBN}
+commands. @xref{Startup}.
+@end ifset
+
@node Sequences
@section Canned Sequences of Commands
@item mi
@cindex mi interpreter
-The newest @sc{gdb/mi} interface (currently @code{mi2}). Used primarily
+The newest @sc{gdb/mi} interface (currently @code{mi3}). Used primarily
by programs wishing to use @value{GDBN} as a backend for a debugger GUI
or an IDE. For more information, see @ref{GDB/MI, ,The @sc{gdb/mi}
Interface}.
+@item mi3
+@cindex mi3 interpreter
+The @sc{gdb/mi} interface introduced in @value{GDBN} 9.1.
+
@item mi2
@cindex mi2 interpreter
-The current @sc{gdb/mi} interface.
+The @sc{gdb/mi} interface introduced in @value{GDBN} 6.0.
@item mi1
@cindex mi1 interpreter
-The @sc{gdb/mi} interface included in @value{GDBN} 5.1, 5.2, and 5.3.
+The @sc{gdb/mi} interface introduced in @value{GDBN} 5.1.
@end table
@item n
next
+@kindex o @r{(SingleKey TUI key)}
+@item o
+nexti. The shortcut letter @samp{o} stands for ``step Over''.
+
@kindex q @r{(SingleKey TUI key)}
@item q
exit the SingleKey mode.
@item s
step
+@kindex i @r{(SingleKey TUI key)}
+@item i
+stepi. The shortcut letter @samp{i} stands for ``step Into''.
+
@kindex u @r{(SingleKey TUI key)}
@item u
up
SingleKey mode is restored. The only way to permanently leave
this mode is by typing @kbd{q} or @kbd{C-x s}.
+@cindex SingleKey keymap name
+If @value{GDBN} was built with Readline 8.0 or later, the TUI
+SingleKey keymap will be named @samp{SingleKey}. This can be used in
+@file{.inputrc} to add additional bindings to this keymap.
@node TUI Commands
@section TUI-specific Commands
@item tui enable
@kindex tui enable
Activate TUI mode. The last active TUI window layout will be used if
-TUI mode has prevsiouly been used in the current debugging session,
+TUI mode has previously been used in the current debugging session,
otherwise a default layout is used.
@item tui disable
decrease it. The @var{name} parameter can be one of @code{src} (the
source window), @code{cmd} (the command window), @code{asm} (the
disassembly window), or @code{regs} (the register display window).
-
-@item tabset @var{nchars}
-@kindex tabset
-Set the width of tab stops to be @var{nchars} characters. This
-setting affects the display of TAB characters in the source and
-assembly windows.
@end table
@node TUI Configuration
@item bold-standout
Use extra bright or bold and standout mode.
@end table
+
+@item set tui tab-width @var{nchars}
+@kindex set tui tab-width
+@kindex tabset
+Set the width of tab stops to be @var{nchars} characters. This
+setting affects the display of TAB characters in the source and
+assembly windows.
@end table
@node Emacs
The application which takes the MI output and presents the state of the
program being debugged to the user is called a @dfn{front end}.
-Although @sc{gdb/mi} is still incomplete, it is currently being used
-by a variety of front ends to @value{GDBN}. This makes it difficult
-to introduce new functionality without breaking existing usage. This
-section tries to minimize the problems by describing how the protocol
-might change.
+Since @sc{gdb/mi} is used by a variety of front ends to @value{GDBN}, changes
+to the MI interface may break existing usage. This section describes how the
+protocol changes and how to request previous version of the protocol when it
+does.
Some changes in MI need not break a carefully designed front end, and
for these the MI version will remain unchanged. The following is a
@end itemize
If the changes are likely to break front ends, the MI version level
-will be increased by one. This will allow the front end to parse the
-output according to the MI version. Apart from mi0, new versions of
-@value{GDBN} will not support old versions of MI and it will be the
-responsibility of the front end to work with the new one.
+will be increased by one. The new versions of the MI protocol are not compatible
+with the old versions. Old versions of MI remain available, allowing front ends
+to keep using them until they are modified to use the latest MI version.
+
+Since @code{--interpreter=mi} always points to the latest MI version, it is
+recommended that front ends request a specific version of MI when launching
+@value{GDBN} (e.g. @code{--interpreter=mi2}) to make sure they get an
+interpreter with the MI version they expect.
+
+The following table gives a summary of the the released versions of the MI
+interface: the version number, the version of GDB in which it first appeared
+and the breaking changes compared to the previous version.
+
+@multitable @columnfractions .05 .05 .9
+@headitem MI version @tab GDB version @tab Breaking changes
+
+@item
+@center 1
+@tab
+@center 5.1
+@tab
+None
+
+@item
+@center 2
+@tab
+@center 6.0
+@tab
+
+@itemize
+@item
+The @code{-environment-pwd}, @code{-environment-directory} and
+@code{-environment-path} commands now returns values using the MI output
+syntax, rather than CLI output syntax.
+
+@item
+@code{-var-list-children}'s @code{children} result field is now a list, rather
+than a tuple.
+
+@item
+@code{-var-update}'s @code{changelist} result field is now a list, rather than
+a tuple.
+@end itemize
+
+@item
+@center 3
+@tab
+@center 9.1
+@tab
-@c Starting with mi3, add a new command -mi-version that prints the MI
-@c version?
+@itemize
+@item
+The output of information about multi-location breakpoints has changed in the
+responses to the @code{-break-insert} and @code{-break-info} commands, as well
+as in the @code{=breakpoint-created} and @code{=breakpoint-modified} events.
+The multiple locations are now placed in a @code{locations} field, whose value
+is a list.
+@end itemize
+
+@end multitable
+
+If your front end cannot yet migrate to a more recent version of the
+MI protocol, you can nevertheless selectively enable specific features
+available in those recent MI versions, using the following commands:
+
+@table @code
+
+@item -fix-multi-location-breakpoint-output
+Use the output for multi-location breakpoints which was introduced by
+MI 3, even when using MI versions 2 or 1. This command has no
+effect when using MI version 3 or later.
+
+@end table
The best way to avoid unexpected changes in MI that might break your front
end is to make your project known to @value{GDBN} developers and
@item =library-loaded,...
Reports that a new library file was loaded by the program. This
-notification has 4 fields---@var{id}, @var{target-name},
-@var{host-name}, and @var{symbols-loaded}. The @var{id} field is an
+notification has 5 fields---@var{id}, @var{target-name},
+@var{host-name}, @var{symbols-loaded} and @var{ranges}. The @var{id} field is an
opaque identifier of the library. For remote debugging case,
@var{target-name} and @var{host-name} fields give the name of the
library file on the target, and on the host respectively. For native
@var{thread-group} field, if present, specifies the id of the thread
group in whose context the library was loaded. If the field is
absent, it means the library was loaded in the context of all present
-thread groups.
+thread groups. The @var{ranges} field specifies the ranges of addresses belonging
+to this library.
@item =library-unloaded,...
Reports that a library was unloaded by the program. This notification
@table @code
@item number
-The breakpoint number. For a breakpoint that represents one location
-of a multi-location breakpoint, this will be a dotted pair, like
-@samp{1.2}.
+The breakpoint number.
@item type
The type of the breakpoint. For ordinary breakpoints this will be
multiple locations. This field will not be present if no address can
be determined. For example, a watchpoint does not have an address.
+@item addr_flags
+Optional field containing any flags related to the address. These flags are
+architecture-dependent; see @ref{Architectures} for their meaning for a
+particular CPU.
+
@item func
If known, the function in which the breakpoint appears.
If not known, this field is not present.
@item what
Some extra data, the exact contents of which are type-dependent.
+@item locations
+This field is present if the breakpoint has multiple locations. It is also
+exceptionally present if the breakpoint is enabled and has a single, disabled
+location.
+
+The value is a list of locations. The format of a location is decribed below.
+
+@end table
+
+A location in a multi-location breakpoint is represented as a tuple with the
+following fields:
+
+@table @code
+
+@item number
+The location number as a dotted pair, like @samp{1.2}. The first digit is the
+number of the parent breakpoint. The second digit is the number of the
+location within that breakpoint.
+
+@item enabled
+This indicates whether the location is enabled, in which case the
+value is @samp{y}, or disabled, in which case the value is @samp{n}.
+Note that this is not the same as the field @code{enable}.
+
+@item addr
+The address of this location as an hexidecimal number.
+
+@item addr_flags
+Optional field containing any flags related to the address. These flags are
+architecture-dependent; see @ref{Architectures} for their meaning for a
+particular CPU.
+
+@item func
+If known, the function in which the location appears.
+If not known, this field is not present.
+
+@item file
+The name of the source file which contains this location, if known.
+If not known, this field is not present.
+
+@item fullname
+The full file name of the source file which contains this location, if
+known. If not known, this field is not present.
+
+@item line
+The line number at which this location appears, if known.
+If not known, this field is not present.
+
+@item thread-groups
+The thread groups this location is in.
+
@end table
For example, here is what the output of @code{-break-insert}
@item addr
The code address for the frame. This field is always present.
+@item addr_flags
+Optional field containing any flags related to the address. These flags are
+architecture-dependent; see @ref{Architectures} for their meaning for a
+particular CPU.
+
@item file
The name of the source files that correspond to the frame's code
address. This field may be absent.
@subsection @sc{gdb/mi} Thread Information
Whenever @value{GDBN} has to report an information about a thread, it
-uses a tuple with the following fields:
+uses a tuple with the following fields. The fields are always present unless
+stated otherwise.
@table @code
@item id
-The global numeric id assigned to the thread by @value{GDBN}. This field is
-always present.
+The global numeric id assigned to the thread by @value{GDBN}.
@item target-id
-Target-specific string identifying the thread. This field is always present.
+The target-specific string identifying the thread.
@item details
Additional information about the thread provided by the target.
It is supposed to be human-readable and not interpreted by the
frontend. This field is optional.
+@item name
+The name of the thread. If the user specified a name using the
+@code{thread name} command, then this name is given. Otherwise, if
+@value{GDBN} can extract the thread name from the target, then that
+name is given. If @value{GDBN} cannot find the thread name, then this
+field is omitted.
+
@item state
-Either @samp{stopped} or @samp{running}, depending on whether the
-thread is presently running. This field is always present.
+The execution state of the thread, either @samp{stopped} or @samp{running},
+depending on whether the thread is presently running.
+
+@item frame
+The stack frame currently executing in the thread. This field is only present
+if the thread is stopped. Its format is documented in
+@ref{GDB/MI Frame Information}.
@item core
The value of this field is an integer number of the processor core the
Whenever a @code{*stopped} record is emitted because the program
stopped after hitting an exception catchpoint (@pxref{Set Catchpoints}),
@value{GDBN} provides the name of the exception that was raised via
-the @code{exception-name} field.
+the @code{exception-name} field. Also, for exceptions that were raised
+with an exception message, @value{GDBN} provides that message via
+the @code{exception-message} field.
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Simple Examples
<- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
frame=@{addr="0x08048564",func="main",
args=[@{name="argc",value="1"@},@{name="argv",value="0xbfc4d4d4"@}],
- file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"@}
+ file="myprog.c",fullname="/home/nickrob/myprog.c",line="68",
+ arch="i386:x86_64"@}
<- (gdb)
-> -exec-continue
<- ^running
*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
value=@{old="-268439212",new="55"@},
frame=@{func="main",args=[],file="recursive2.c",
-fullname="/home/foo/bar/recursive2.c",line="5"@}
+fullname="/home/foo/bar/recursive2.c",line="5",arch="i386:x86_64"@}
(gdb)
@end smallexample
wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
frame=@{func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13",
+arch="i386:x86_64"@}
(gdb)
-exec-continue
^running
frame=@{func="callee3",args=[@{name="strarg",
value="0x11940 \"A string argument.\""@}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18",
+arch="i386:x86_64"@}
(gdb)
@end smallexample
value=@{old="-276895068",new="3"@},
frame=@{func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13",
+arch="i386:x86_64"@}
(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
frame=@{func="callee3",args=[@{name="strarg",
value="0x11940 \"A string argument.\""@}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18",
+arch="i386:x86_64"@}
(gdb)
-break-list
^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
@menu
* Shared Library GDB/MI Catchpoint Commands::
* Ada Exception GDB/MI Catchpoint Commands::
+* C++ Exception GDB/MI Catchpoint Commands::
@end menu
@node Shared Library GDB/MI Catchpoint Commands
(gdb)
@end smallexample
+@subheading The @code{-catch-handlers} Command
+@findex -catch-handlers
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-handlers [ -c @var{condition}] [ -d ] [ -e @var{exception-name} ]
+ [ -t ]
+@end smallexample
+
+Add a catchpoint stopping when Ada exceptions are handled.
+By default, the command stops the program when any Ada exception
+gets handled. But it is also possible, by using some of the
+optional parameters described below, to create more selective
+catchpoints.
+
+The possible optional parameters for this command are:
+
+@table @samp
+@item -c @var{condition}
+Make the catchpoint conditional on @var{condition}.
+@item -d
+Create a disabled catchpoint.
+@item -e @var{exception-name}
+Only stop when @var{exception-name} is handled.
+@item -t
+Create a temporary catchpoint.
+@end table
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{catch handlers}.
+
+@subsubheading Example
+
+@smallexample
+-catch-handlers -e Constraint_Error
+^done,bkptno="4",bkpt=@{number="4",type="breakpoint",disp="keep",
+enabled="y",addr="0x0000000000402f68",
+what="`Constraint_Error' Ada exception handlers",thread-groups=["i1"],
+times="0",original-location="__gnat_begin_handler"@}
+(gdb)
+@end smallexample
+
+@node C++ Exception GDB/MI Catchpoint Commands
+@subsection C@t{++} Exception @sc{gdb/mi} Catchpoints
+
+The following @sc{gdb/mi} commands can be used to create catchpoints
+that stop the execution when C@t{++} exceptions are being throw, rethrown,
+or caught.
+
+@subheading The @code{-catch-throw} Command
+@findex -catch-throw
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-throw [ -t ] [ -r @var{regexp}]
+@end smallexample
+
+Stop when the debuggee throws a C@t{++} exception. If @var{regexp} is
+given, then only exceptions whose type matches the regular expression
+will be caught.
+
+If @samp{-t} is given, then the catchpoint is enabled only for one
+stop, the catchpoint is automatically deleted after stopping once for
+the event.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{catch throw}
+and @samp{tcatch throw} (@pxref{Set Catchpoints}).
+
+@subsubheading Example
+
+@smallexample
+-catch-throw -r exception_type
+^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y",
+ what="exception throw",catch-type="throw",
+ thread-groups=["i1"],
+ regexp="exception_type",times="0"@}
+(gdb)
+-exec-run
+^running
+(gdb)
+~"\n"
+~"Catchpoint 1 (exception thrown), 0x00007ffff7ae00ed
+ in __cxa_throw () from /lib64/libstdc++.so.6\n"
+*stopped,bkptno="1",reason="breakpoint-hit",disp="keep",
+ frame=@{addr="0x00007ffff7ae00ed",func="__cxa_throw",
+ args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"@},
+ thread-id="1",stopped-threads="all",core="6"
+(gdb)
+@end smallexample
+
+@subheading The @code{-catch-rethrow} Command
+@findex -catch-rethrow
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-rethrow [ -t ] [ -r @var{regexp}]
+@end smallexample
+
+Stop when a C@t{++} exception is re-thrown. If @var{regexp} is given,
+then only exceptions whose type matches the regular expression will be
+caught.
+
+If @samp{-t} is given, then the catchpoint is enabled only for one
+stop, the catchpoint is automatically deleted after the first event is
+caught.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{catch rethrow}
+and @samp{tcatch rethrow} (@pxref{Set Catchpoints}).
+
+@subsubheading Example
+
+@smallexample
+-catch-rethrow -r exception_type
+^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y",
+ what="exception rethrow",catch-type="rethrow",
+ thread-groups=["i1"],
+ regexp="exception_type",times="0"@}
+(gdb)
+-exec-run
+^running
+(gdb)
+~"\n"
+~"Catchpoint 1 (exception rethrown), 0x00007ffff7ae00ed
+ in __cxa_rethrow () from /lib64/libstdc++.so.6\n"
+*stopped,bkptno="1",reason="breakpoint-hit",disp="keep",
+ frame=@{addr="0x00007ffff7ae00ed",func="__cxa_rethrow",
+ args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"@},
+ thread-id="1",stopped-threads="all",core="6"
+(gdb)
+@end smallexample
+
+@subheading The @code{-catch-catch} Command
+@findex -catch-catch
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-catch [ -t ] [ -r @var{regexp}]
+@end smallexample
+
+Stop when the debuggee catches a C@t{++} exception. If @var{regexp}
+is given, then only exceptions whose type matches the regular
+expression will be caught.
+
+If @samp{-t} is given, then the catchpoint is enabled only for one
+stop, the catchpoint is automatically deleted after the first event is
+caught.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} commands are @samp{catch catch}
+and @samp{tcatch catch} (@pxref{Set Catchpoints}).
+
+@subsubheading Example
+
+@smallexample
+-catch-catch -r exception_type
+^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y",
+ what="exception catch",catch-type="catch",
+ thread-groups=["i1"],
+ regexp="exception_type",times="0"@}
+(gdb)
+-exec-run
+^running
+(gdb)
+~"\n"
+~"Catchpoint 1 (exception caught), 0x00007ffff7ae00ed
+ in __cxa_begin_catch () from /lib64/libstdc++.so.6\n"
+*stopped,bkptno="1",reason="breakpoint-hit",disp="keep",
+ frame=@{addr="0x00007ffff7ae00ed",func="__cxa_begin_catch",
+ args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"@},
+ thread-id="1",stopped-threads="all",core="6"
+(gdb)
+@end smallexample
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Program Context
@section @sc{gdb/mi} Program Context
@subsubheading Result
-The result is a list of threads. The following attributes are
-defined for a given thread:
+The result contains the following attributes:
@table @samp
-@item current
-This field exists only for the current thread. It has the value @samp{*}.
-
-@item id
-The global identifier that @value{GDBN} uses to refer to the thread.
-
-@item target-id
-The identifier that the target uses to refer to the thread.
-
-@item details
-Extra information about the thread, in a target-specific format. This
-field is optional.
-
-@item name
-The name of the thread. If the user specified a name using the
-@code{thread name} command, then this name is given. Otherwise, if
-@value{GDBN} can extract the thread name from the target, then that
-name is given. If @value{GDBN} cannot find the thread name, then this
-field is omitted.
-
-@item frame
-The stack frame currently executing in the thread.
-
-@item state
-The thread's state. The @samp{state} field may have the following
-values:
-
-@table @code
-@item stopped
-The thread is stopped. Frame information is available for stopped
-threads.
-
-@item running
-The thread is running. There's no frame information for running
-threads.
-
-@end table
+@item threads
+A list of threads. The format of the elements of the list is described in
+@ref{GDB/MI Thread Information}.
-@item core
-If @value{GDBN} can find the CPU core on which this thread is running,
-then this field is the core identifier. This field is optional.
+@item current-thread-id
+The global id of the currently selected thread. This field is omitted if there
+is no selected thread (for example, when the selected inferior is not running,
+and therefore has no threads) or if a @var{thread-id} argument was passed to
+the command.
@end table
@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
frame=@{level="0",addr="0x0804891f",func="foo",
args=[@{name="i",value="10"@}],
- file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},
+ file="/tmp/a.c",fullname="/tmp/a.c",line="158",arch="i386:x86_64"@},
state="running"@}],
current-thread-id="1"
(gdb)
^done,new-thread-id="3",
frame=@{level="0",func="vprintf",
args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
-@{name="arg",value="0x2"@}],file="vprintf.c",line="31"@}
+@{name="arg",value="0x2"@}],file="vprintf.c",line="31",arch="i386:x86_64"@}
(gdb)
@end smallexample
@@Hello world
*stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame=@{
func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c",
-line="13"@}
+line="13",arch="i386:x86_64"@}
(gdb)
@end smallexample
(gdb)
@@hello from foo
*stopped,reason="function-finished",frame=@{func="main",args=[],
-file="hello.c",fullname="/home/foo/bar/hello.c",line="7"@}
+file="hello.c",fullname="/home/foo/bar/hello.c",line="7",arch="i386:x86_64"@}
(gdb)
@end smallexample
(gdb)
*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
args=[@{name="a",value="1"],@{name="b",value="9"@}@},
-file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+arch="i386:x86_64"@},
gdb-result-var="$1",return-value="0"
(gdb)
@end smallexample
(gdb)
111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
frame=@{addr="0x00010140",func="foo",args=[],file="try.c",
-fullname="/home/foo/bar/try.c",line="13"@}
+fullname="/home/foo/bar/try.c",line="13",arch="i386:x86_64"@}
(gdb)
(gdb)
000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
frame=@{func="callee4",args=[],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
+arch="i386:x86_64"@}
(gdb)
205-break-delete
205^done
args=[@{name="strarg",
value="0x11940 \"A string argument.\""@}],
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18",
+arch="i386:x86_64"@}
(gdb)
@end smallexample
(gdb)
*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
frame=@{func="main",args=[],file="recursive2.c",
-fullname="/home/foo/bar/recursive2.c",line="4"@}
+fullname="/home/foo/bar/recursive2.c",line="4",arch="i386:x86_64"@}
(gdb)
@end smallexample
*stopped,reason="end-stepping-range",
frame=@{func="foo",args=[@{name="a",value="10"@},
@{name="b",value="0"@}],file="recursive2.c",
-fullname="/home/foo/bar/recursive2.c",line="11"@}
+fullname="/home/foo/bar/recursive2.c",line="11",arch="i386:x86_64"@}
(gdb)
@end smallexample
(gdb)
*stopped,reason="end-stepping-range",
frame=@{func="foo",args=[],file="try.c",
-fullname="/home/foo/bar/try.c",line="10"@}
+fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"@}
(gdb)
-exec-step-instruction
^running
(gdb)
*stopped,reason="end-stepping-range",
frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",
-fullname="/home/foo/bar/try.c",line="10"@}
+fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"@}
(gdb)
@end smallexample
(gdb)
x = 55
*stopped,reason="location-reached",frame=@{func="main",args=[],
-file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"@}
+file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6",
+arch="i386:x86_64"@}
(gdb)
@end smallexample
-stack-info-frame
^done,frame=@{level="1",addr="0x0001076c",func="callee3",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@}
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17",
+arch="i386:x86_64"@}
(gdb)
@end smallexample
stack=[
frame=@{level="0",addr="0x00010734",func="callee4",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
+arch="i386:x86_64"@},
frame=@{level="1",addr="0x0001076c",func="callee3",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17",
+arch="i386:x86_64"@},
frame=@{level="2",addr="0x0001078c",func="callee2",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22",
+arch="i386:x86_64"@},
frame=@{level="3",addr="0x000107b4",func="callee1",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27",
+arch="i386:x86_64"@},
frame=@{level="4",addr="0x000107e0",func="main",
file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
-fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}]
+fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32",
+arch="i386:x86_64"@}]
(gdb)
-stack-list-arguments 0
^done,
@item @var{from}
The shared library where this function is defined. This is only given
if the frame's function is not known.
+@item @var{arch}
+Frame's architecture.
@end table
If invoked without arguments, this command prints a backtrace for the
-stack-list-frames
^done,stack=
[frame=@{level="0",addr="0x0001076c",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11",
+ arch="i386:x86_64"@},
frame=@{level="1",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="2",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="4",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="5",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="6",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="7",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="8",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="9",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="10",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="11",addr="0x00010738",func="main",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"@}]
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4",
+ arch="i386:x86_64"@}]
(gdb)
@end smallexample
-stack-list-frames 3 5
^done,stack=
[frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="4",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@},
frame=@{level="5",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@}]
(gdb)
@end smallexample
-stack-list-frames 3 3
^done,stack=
[frame=@{level="3",addr="0x000107a4",func="foo",
- file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
+ file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14",
+ arch="i386:x86_64"@}]
(gdb)
@end smallexample
@smallexample
-data-disassemble
[ -s @var{start-addr} -e @var{end-addr} ]
+ | [ -a @var{addr} ]
| [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
-- @var{mode}
@end smallexample
is the beginning address (or @code{$pc})
@item @var{end-addr}
is the end address
+@item @var{addr}
+is an address anywhere within (or the name of) the function to
+disassemble. If an address is specified, the whole function
+surrounding that address will be disassembled. If a name is
+specified, the whole function with that name will be disassembled.
@item @var{filename}
is the name of the file to disassemble
@item @var{linenum}
(gdb)
*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame=@{
func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c",
-line="5"@}
+line="5",arch="powerpc"@}
(gdb)
-data-list-changed-registers
^done,changed-registers=["0","1","2","4","5","6","7","8","9",
(gdb)
@end smallexample
-@ignore
@subheading The @code{-file-list-shared-libraries} Command
@findex -file-list-shared-libraries
@subsubheading Synopsis
@smallexample
- -file-list-shared-libraries
+ -file-list-shared-libraries [ @var{regexp} ]
@end smallexample
List the shared libraries in the program.
+With a regular expression @var{regexp}, only those libraries whose
+names match @var{regexp} are listed.
@subsubheading @value{GDBN} Command
-The corresponding @value{GDBN} command is @samp{info shared}.
+The corresponding @value{GDBN} command is @samp{info shared}. The fields
+have a similar meaning to the @code{=library-loaded} notification.
+The @code{ranges} field specifies the multiple segments belonging to this
+library. Each range has the following fields:
+
+@table @samp
+@item from
+The address defining the inclusive lower bound of the segment.
+@item to
+The address defining the exclusive upper bound of the segment.
+@end table
@subsubheading Example
-N.A.
+@smallexample
+(gdb)
+-file-list-exec-source-files
+^done,shared-libraries=[
+@{id="/lib/libfoo.so",target-name="/lib/libfoo.so",host-name="/lib/libfoo.so",symbols-loaded="1",thread-group="i1",ranges=[@{from="0x72815989",to="0x728162c0"@}]@},
+@{id="/lib/libbar.so",target-name="/lib/libbar.so",host-name="/lib/libbar.so",symbols-loaded="1",thread-group="i1",ranges=[@{from="0x76ee48c0",to="0x76ee9160"@}]@}]
+(gdb)
+@end smallexample
+@ignore
@subheading The @code{-file-list-symbol-files} Command
@findex -file-list-symbol-files
@item exec-run-start-option
Indicates that the @code{-exec-run} command supports the @option{--start}
option (@pxref{GDB/MI Program Execution}).
+@item data-disassemble-a-option
+Indicates that the @code{-data-disassemble} command supports the @option{-a}
+option (@pxref{GDB/MI Data Manipulation}).
@end ftable
@subheading The @code{-list-target-features} Command
frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@},
@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}],
- file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},state="running"@}]]
+ file="/tmp/a.c",fullname="/tmp/a.c",line="158",arch="i386:x86_64"@},state="running"@}]]
-list-thread-groups --available
^done,groups=[@{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]@}]
-list-thread-groups --available --recurse 1
*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
frame=@{addr="0x080484ed",func="main",args=[@{name="argc",value="1"@},
@{name="argv",value="0xbfb60364"@}],file="myprog.c",
-fullname="/home/nickrob/myprog.c",line="73"@}
+fullname="/home/nickrob/myprog.c",line="73",arch="i386:x86_64"@}
(gdb)
@end smallexample
+@subheading The @code{-complete} Command
+@findex -complete
+
+@subheading Synopsis
+
+@smallexample
+-complete @var{command}
+@end smallexample
+
+Show a list of completions for partially typed CLI @var{command}.
+
+This command is intended for @sc{gdb/mi} frontends that cannot use two separate
+CLI and MI channels --- for example: because of lack of PTYs like on Windows or
+because @value{GDBN} is used remotely via a SSH connection.
+
+@subheading Result
+
+The result consists of two or three fields:
+
+@table @samp
+@item completion
+This field contains the completed @var{command}. If @var{command}
+has no known completions, this field is omitted.
+
+@item matches
+This field contains a (possibly empty) array of matches. It is always present.
+
+@item max_completions_reached
+This field contains @code{1} if number of known completions is above
+@code{max-completions} limit (@pxref{Completion}), otherwise it contains
+@code{0}. It is always present.
+
+@end table
+
+@subheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{complete}.
+
+@subheading Example
+
+@smallexample
+(gdb)
+-complete br
+^done,completion="break",
+ matches=["break","break-range"],
+ max_completions_reached="0"
+(gdb)
+-complete "b ma"
+^done,completion="b ma",
+ matches=["b madvise","b main"],max_completions_reached="0"
+(gdb)
+-complete "b push_b"
+^done,completion="b push_back(",
+ matches=[
+ "b A::push_back(void*)",
+ "b std::string::push_back(char)",
+ "b std::vector<int, std::allocator<int> >::push_back(int&&)"],
+ max_completions_reached="0"
+(gdb)
+-complete "nonexist"
+^done,matches=[],max_completions_reached="0"
+(gdb)
+
+@end smallexample
+
@node Annotations
@chapter @value{GDBN} Annotations
@heading Tools/Packages Necessary for Building @value{GDBN}
@table @asis
-@item ISO C90 compiler
-@value{GDBN} is written in ISO C90. It should be buildable with any
-working C90 compiler, e.g.@: GCC.
+@item C@t{++}11 compiler
+@value{GDBN} is written in C@t{++}11. It should be buildable with any
+recent C@t{++}11 compiler, e.g.@: GCC.
+@item GNU make
+@value{GDBN}'s build system relies on features only found in the GNU
+make program. Other variants of @code{make} will not work.
@end table
@heading Tools/Packages Optional for Building @value{GDBN}
@pxref{Branch Trace Configuration Format})
@end itemize
-@item zlib
-@cindex compressed debug sections
-@value{GDBN} will use the @samp{zlib} library, if available, to read
-compressed debug sections. Some linkers, such as GNU gold, are capable
-of producing binaries with compressed debug sections. If @value{GDBN}
-is compiled with @samp{zlib}, it will be able to read the debug
-information in such binaries.
-
-The @samp{zlib} library is likely included with your operating system
-distribution; if it is not, you can get the latest version from
-@url{http://zlib.net}.
+@item Guile
+@value{GDBN} can be scripted using GNU Guile. @xref{Guile}. By
+default, @value{GDBN} will be compiled if the Guile libraries are
+installed and are found by @file{configure}. You can use the
+@code{--with-guile} option to request Guile, and pass either the Guile
+version number or the file name of the relevant @code{pkg-config}
+program to choose a particular version of Guile.
@item iconv
@value{GDBN}'s features related to character sets (@pxref{Character
other systems also provide a working @code{iconv}.
If @value{GDBN} is using the @code{iconv} program which is installed
-in a non-standard place, you will need to tell @value{GDBN} where to find it.
-This is done with @option{--with-iconv-bin} which specifies the
-directory that contains the @code{iconv} program.
+in a non-standard place, you will need to tell @value{GDBN} where to
+find it. This is done with @option{--with-iconv-bin} which specifies
+the directory that contains the @code{iconv} program. This program is
+run in order to make a list of the available character sets.
-On systems without @code{iconv}, you can install GNU Libiconv. If you
-have previously installed Libiconv, you can use the
-@option{--with-libiconv-prefix} option to configure.
+On systems without @code{iconv}, you can install GNU Libiconv. If
+Libiconv is installed in a standard place, @value{GDBN} will
+automatically use it if it is needed. If you have previously
+installed Libiconv in a non-standard place, you can use the
+@option{--with-libiconv-prefix} option to @file{configure}.
@value{GDBN}'s top-level @file{configure} and @file{Makefile} will
arrange to build Libiconv if a directory named @file{libiconv} appears
if the operating system does not provide a suitable @code{iconv}
implementation, then the just-built library will automatically be used
by @value{GDBN}. One easy way to set this up is to download GNU
-Libiconv, unpack it, and then rename the directory holding the
-Libiconv source code to @samp{libiconv}.
+Libiconv, unpack it inside the top-level directory of the @value{GDBN}
+source tree, and then rename the directory holding the Libiconv source
+code to @samp{libiconv}.
+
+@item lzma
+@value{GDBN} can support debugging sections that are compressed with
+the LZMA library. @xref{MiniDebugInfo}. If this library is not
+included with your operating system, you can find it in the xz package
+at @url{http://tukaani.org/xz/}. If the LZMA library is available in
+the usual place, then the @file{configure} script will use it
+automatically. If it is installed in an unusual path, you can use the
+@option{--with-lzma-prefix} option to specify its location.
+
+@item MPFR
+@anchor{MPFR}
+@value{GDBN} can use the GNU MPFR multiple-precision floating-point
+library. This library may be included with your operating system
+distribution; if it is not, you can get the latest version from
+@url{http://www.mpfr.org}. The @file{configure} script will search
+for this library in several standard locations; if it is installed
+in an unusual path, you can use the @option{--with-libmpfr-prefix}
+option to specify its location.
+
+GNU MPFR is used to emulate target floating-point arithmetic during
+expression evaluation when the target uses different floating-point
+formats than the host. If GNU MPFR it is not available, @value{GDBN}
+will fall back to using host floating-point arithmetic.
+
+@item Python
+@value{GDBN} can be scripted using Python language. @xref{Python}.
+By default, @value{GDBN} will be compiled if the Python libraries are
+installed and are found by @file{configure}. You can use the
+@code{--with-python} option to request Python, and pass either the
+file name of the relevant @code{python} executable, or the name of the
+directory in which Python is installed, to choose a particular
+installation of Python.
+
+@item zlib
+@cindex compressed debug sections
+@value{GDBN} will use the @samp{zlib} library, if available, to read
+compressed debug sections. Some linkers, such as GNU gold, are capable
+of producing binaries with compressed debug sections. If @value{GDBN}
+is compiled with @samp{zlib}, it will be able to read the debug
+information in such binaries.
+
+The @samp{zlib} library is likely included with your operating system
+distribution; if it is not, you can get the latest version from
+@url{http://zlib.net}.
@end table
@node Running Configure
@item gdb-@value{GDBVN}/readline
source for the @sc{gnu} command-line interface
-
-@item gdb-@value{GDBVN}/glob
-source for the @sc{gnu} filename pattern-matching subroutine
-
-@item gdb-@value{GDBVN}/mmalloc
-source for the @sc{gnu} memory-mapped malloc package
@end table
+There may be other subdirectories as well.
+
The simplest way to configure and build @value{GDBN} is to run @file{configure}
from the @file{gdb-@var{version-number}} source directory, which in
this example is the @file{gdb-@value{GDBVN}} directory.
@smallexample
cd gdb-@value{GDBVN}
-./configure @var{host}
+./configure
make
@end smallexample
-@noindent
-where @var{host} is an identifier such as @samp{sun4} or
-@samp{decstation}, that identifies the platform where @value{GDBN} will run.
-(You can often leave off @var{host}; @file{configure} tries to guess the
-correct value by examining your system.)
-
-Running @samp{configure @var{host}} and then running @code{make} builds the
-@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty}
-libraries, then @code{gdb} itself. The configured source files, and the
-binaries, are left in the corresponding source directories.
+Running @samp{configure} and then running @code{make} builds the
+included supporting libraries, then @code{gdb} itself. The configured
+source files, and the binaries, are left in the corresponding source
+directories.
@need 750
@file{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
shell, you may need to run @code{sh} on it explicitly:
@smallexample
-sh configure @var{host}
+sh configure
@end smallexample
-If you run @file{configure} from a directory that contains source
-directories for multiple libraries or programs, such as the
-@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN},
-@file{configure}
-creates configuration files for every directory level underneath (unless
-you tell it not to, with the @samp{--norecursion} option).
-
You should run the @file{configure} script from the top directory in the
source tree, the @file{gdb-@var{version-number}} directory. If you run
@file{configure} from one of the subdirectories, you will configure only
directories of the @file{gdb} subdirectory. This leads to build errors
about missing include files such as @file{bfd/bfd.h}.
-You can install @code{@value{GDBP}} anywhere; it has no hardwired paths.
-However, you should make sure that the shell on your path (named by
-the @samp{SHELL} environment variable) is publicly readable. Remember
-that @value{GDBN} uses the shell to start your program---some systems refuse to
-let @value{GDBN} debug child processes whose programs are not readable.
+You can install @code{@value{GDBN}} anywhere. The best way to do this
+is to pass the @code{--prefix} option to @code{configure}, and then
+install it with @code{make install}.
@node Separate Objdir
@section Compiling @value{GDBN} in Another Directory
cd gdb-@value{GDBVN}
mkdir ../gdb-sun4
cd ../gdb-sun4
-../gdb-@value{GDBVN}/configure sun4
+../gdb-@value{GDBVN}/configure
make
@end group
@end smallexample
@section @file{configure} Options
Here is a summary of the @file{configure} options and arguments that
-are most often useful for building @value{GDBN}. @file{configure} also has
-several other options not listed here. @inforef{What Configure
-Does,,configure.info}, for a full explanation of @file{configure}.
+are most often useful for building @value{GDBN}. @file{configure}
+also has several other options not listed here. @inforef{Running
+configure scripts,,autoconf.info}, for a full
+explanation of @file{configure}.
@smallexample
configure @r{[}--help@r{]}
@r{[}--prefix=@var{dir}@r{]}
@r{[}--exec-prefix=@var{dir}@r{]}
@r{[}--srcdir=@var{dirname}@r{]}
- @r{[}--norecursion@r{]} @r{[}--rm@r{]}
@r{[}--target=@var{target}@r{]}
- @var{host}
@end smallexample
@noindent
@c avoid splitting the warning from the explanation:
@need 2000
@item --srcdir=@var{dirname}
-@strong{Warning: using this option requires @sc{gnu} @code{make}, or another
-@code{make} that implements the @code{VPATH} feature.}@*
Use this option to make configurations in directories separate from the
@value{GDBN} source directories. Among other things, you can use this to
build (or maintain) several configurations simultaneously, in separate
the working directory in parallel to the source directories below
@var{dirname}.
-@item --norecursion
-Configure only the directory level where @file{configure} is executed; do not
-propagate configuration to subdirectories.
-
@item --target=@var{target}
Configure @value{GDBN} for cross-debugging programs running on the specified
@var{target}. Without this option, @value{GDBN} is configured to debug
programs that run on the same machine (@var{host}) as @value{GDBN} itself.
-There is no convenient way to generate a list of all available targets.
+There is no convenient way to generate a list of all available
+targets. Also see the @code{--enable-targets} option, below.
+@end table
+
+There are many other options that are specific to @value{GDBN}. This
+lists just the most common ones; there are some very specialized
+options not described here.
+
+@table @code
+@item --enable-targets=@r{[}@var{target}@r{]}@dots{}
+@itemx --enable-targets=all
+Configure @value{GDBN} for cross-debugging programs running on the
+specified list of targets. The special value @samp{all} configures
+@value{GDBN} for debugging programs running on any target it supports.
-@item @var{host} @dots{}
-Configure @value{GDBN} to run on the specified @var{host}.
+@item --with-gdb-datadir=@var{path}
+Set the @value{GDBN}-specific data directory. @value{GDBN} will look
+here for certain supporting files or scripts. This defaults to the
+@file{gdb} subdirectory of @samp{datadi} (which can be set using
+@code{--datadir}).
-There is no convenient way to generate a list of all available hosts.
-@end table
+@item --with-relocated-sources=@var{dir}
+Sets up the default source path substitution rule so that directory
+names recorded in debug information will be automatically adjusted for
+any directory under @var{dir}. @var{dir} should be a subdirectory of
+@value{GDBN}'s configured prefix, the one mentioned in the
+@code{--prefix} or @code{--exec-prefix} options to configure. This
+option is useful if GDB is supposed to be moved to a different place
+after it is built.
+
+@item --enable-64-bit-bfd
+Enable 64-bit support in BFD on 32-bit hosts.
+
+@item --disable-gdbmi
+Build @value{GDBN} without the GDB/MI machine interface
+(@pxref{GDB/MI}).
+
+@item --enable-tui
+Build @value{GDBN} with the text-mode full-screen user interface
+(TUI). Requires a curses library (ncurses and cursesX are also
+supported).
+
+@item --with-curses
+Use the curses library instead of the termcap library, for text-mode
+terminal operations.
+
+@item --with-libunwind-ia64
+Use the libunwind library for unwinding function call stack on ia64
+target platforms. See http://www.nongnu.org/libunwind/index.html for
+details.
+
+@item --with-system-readline
+Use the readline library installed on the host, rather than the
+library supplied as part of @value{GDBN}. Readline 7 or newer is
+required; this is enforced by the build system.
+
+@item --with-system-zlib
+Use the zlib library installed on the host, rather than the library
+supplied as part of @value{GDBN}.
+
+@item --with-expat
+Build @value{GDBN} with Expat, a library for XML parsing. (Done by
+default if libexpat is installed and found at configure time.) This
+library is used to read XML files supplied with @value{GDBN}. If it
+is unavailable, some features, such as remote protocol memory maps,
+target descriptions, and shared library lists, that are based on XML
+files, will not be available in @value{GDBN}. If your host does not
+have libexpat installed, you can get the latest version from
+`http://expat.sourceforge.net'.
+
+@item --with-libiconv-prefix@r{[}=@var{dir}@r{]}
+
+Build @value{GDBN} with GNU libiconv, a character set encoding
+conversion library. This is not done by default, as on GNU systems
+the @code{iconv} that is built in to the C library is sufficient. If
+your host does not have a working @code{iconv}, you can get the latest
+version of GNU iconv from `https://www.gnu.org/software/libiconv/'.
+
+@value{GDBN}'s build system also supports building GNU libiconv as
+part of the overall build. @xref{Requirements}.
+
+@item --with-lzma
+Build @value{GDBN} with LZMA, a compression library. (Done by default
+if liblzma is installed and found at configure time.) LZMA is used by
+@value{GDBN}'s "mini debuginfo" feature, which is only useful on
+platforms using the ELF object file format. If your host does not
+have liblzma installed, you can get the latest version from
+`https://tukaani.org/xz/'.
+
+@item --with-mpfr
+Build @value{GDBN} with GNU MPFR, a library for multiple-precision
+floating-point computation with correct rounding. (Done by default if
+GNU MPFR is installed and found at configure time.) This library is
+used to emulate target floating-point arithmetic during expression
+evaluation when the target uses different floating-point formats than
+the host. If GNU MPFR is not available, @value{GDBN} will fall back
+to using host floating-point arithmetic. If your host does not have
+GNU MPFR installed, you can get the latest version from
+`http://www.mpfr.org'.
+
+@item --with-python@r{[}=@var{python}@r{]}
+Build @value{GDBN} with Python scripting support. (Done by default if
+libpython is present and found at configure time.) Python makes
+@value{GDBN} scripting much more powerful than the restricted CLI
+scripting language. If your host does not have Python installed, you
+can find it on `http://www.python.org/download/'. The oldest version
+of Python supported by GDB is 2.6. The optional argument @var{python}
+is used to find the Python headers and libraries. It can be either
+the name of a Python executable, or the name of the directory in which
+Python is installed.
+
+@item --with-guile[=GUILE]'
+Build @value{GDBN} with GNU Guile scripting support. (Done by default
+if libguile is present and found at configure time.) If your host
+does not have Guile installed, you can find it at
+`https://www.gnu.org/software/guile/'. The optional argument GUILE
+can be a version number, which will cause @code{configure} to try to
+use that version of Guile; or the file name of a @code{pkg-config}
+executable, which will be queried to find the information needed to
+compile and link against Guile.
+
+@item --without-included-regex
+Don't use the regex library included with @value{GDBN} (as part of the
+libiberty library). This is the default on hosts with version 2 of
+the GNU C library.
+
+@item --with-sysroot=@var{dir}
+Use @var{dir} as the default system root directory for libraries whose
+file names begin with @file{/lib}' or @file{/usr/lib'}. (The value of
+@var{dir} can be modified at run time by using the @command{set
+sysroot} command.) If @var{dir} is under the @value{GDBN} configured
+prefix (set with @code{--prefix} or @code{--exec-prefix options}, the
+default system root will be automatically adjusted if and when
+@value{GDBN} is moved to a different location.
-There are many other options available as well, but they are generally
-needed for special purposes only.
+@item --with-system-gdbinit=@var{file}
+Configure @value{GDBN} to automatically load a system-wide init file.
+@var{file} should be an absolute file name. If @var{file} is in a
+directory under the configured prefix, and @value{GDBN} is moved to
+another location after being built, the location of the system-wide
+init file will be adjusted accordingly.
+
+@item --with-system-gdbinit-dir=@var{directory}
+Configure @value{GDBN} to automatically load init files from a
+system-wide directory. @var{directory} should be an absolute directory
+name. If @var{directory} is in a directory under the configured
+prefix, and @value{GDBN} is moved to another location after being
+built, the location of the system-wide init directory will be
+adjusted accordingly.
+
+@item --enable-build-warnings
+When building the @value{GDBN} sources, ask the compiler to warn about
+any code which looks even vaguely suspicious. It passes many
+different warning flags, depending on the exact version of the
+compiler you are using.
+
+@item --enable-werror
+Treat compiler warnings as werrors. It adds the @code{-Werror} flag
+to the compiler, which will fail the compilation if the compiler
+outputs any warning messages.
+
+@item --enable-ubsan
+Enable the GCC undefined behavior sanitizer. This is disabled by
+default, but passing @code{--enable-ubsan=yes} or
+@code{--enable-ubsan=auto} to @code{configure} will enable it. The
+undefined behavior sanitizer checks for C@t{++} undefined behavior.
+It has a performance cost, so if you are looking at @value{GDBN}'s
+performance, you should disable it. The undefined behavior sanitizer
+was first introduced in GCC 4.9.
+@end table
@node System-wide configuration
@section System-wide configuration and settings
@cindex system-wide init file
-@value{GDBN} can be configured to have a system-wide init file;
-this file will be read and executed at startup (@pxref{Startup, , What
-@value{GDBN} does during startup}).
+@value{GDBN} can be configured to have a system-wide init file and a
+system-wide init file directory; this file and files in that directory
+(if they have a recognized file extension) will be read and executed at
+startup (@pxref{Startup, , What @value{GDBN} does during startup}).
-Here is the corresponding configure option:
+Here are the corresponding configure options:
@table @code
@item --with-system-gdbinit=@var{file}
Specify that the default location of the system-wide init file is
@var{file}.
+@item --with-system-gdbinit-dir=@var{directory}
+Specify that the default location of the system-wide init file directory
+is @var{directory}.
@end table
If @value{GDBN} has been configured with the option @option{--prefix=$prefix},
-it may be subject to relocation. Two possible cases:
+they may be subject to relocation. Two possible cases:
@itemize @bullet
@item
-If the default location of this init file contains @file{$prefix},
+If the default location of this init file/directory contains @file{$prefix},
it will be subject to relocation. Suppose that the configure options
are @option{--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit};
if @value{GDBN} is moved from @file{$prefix} to @file{$install}, the system
started with the @code{set data-directory} command, the file will not be
reread.
+This applies similarly to the system-wide directory specified in
+@option{--with-system-gdbinit-dir}.
+
+Any supported scripting language can be used for these init files, as long
+as the file extension matches the scripting language. To be interpreted
+as regular @value{GDBN} commands, the files needs to have a @file{.gdb}
+extension.
+
@menu
* System-wide Configuration Scripts:: Installed System-wide Configuration Scripts
@end menu
Print the entire architecture configuration. The optional argument
@var{file} names the file where the output goes.
-@kindex maint print c-tdesc
+@kindex maint print c-tdesc @r{[}@var{file}@r{]}
@item maint print c-tdesc
-Print the current target description (@pxref{Target Descriptions}) as
-a C source file. The created source file can be used in @value{GDBN}
-when an XML parser is not available to parse the description.
+Print the target description (@pxref{Target Descriptions}) as
+a C source file. By default, the target description is for the current
+target, but if the optional argument @var{file} is provided, that file
+is used to produce the description. The @var{file} should be an XML
+document, of the form described in @ref{Target Description Format}.
+The created source file is built into @value{GDBN} when @value{GDBN} is
+built again. This command is used by developers after they add or
+modify XML target descriptions.
+
+@kindex maint check xml-descriptions
+@item maint check xml-descriptions @var{dir}
+Check that the target descriptions dynamically created by @value{GDBN}
+equal the descriptions created from XML files found in @var{dir}.
+
+@anchor{maint check libthread-db}
+@kindex maint check libthread-db
+@item maint check libthread-db
+Run integrity checks on the current inferior's thread debugging
+library. This exercises all @code{libthread_db} functionality used by
+@value{GDBN} on GNU/Linux systems, and by extension also exercises the
+@code{proc_service} functions provided by @value{GDBN} that
+@code{libthread_db} uses. Note that parts of the test may be skipped
+on some platforms when debugging core files.
@kindex maint print dummy-frames
@item maint print dummy-frames
@kindex maint selftest
@cindex self tests
+@item maint selftest @r{[}@var{filter}@r{]}
Run any self tests that were compiled in to @value{GDBN}. This will
print a message showing how many tests were run, and how many failed.
+If a @var{filter} is passed, only the tests with @var{filter} in their
+name will by ran.
+
+@kindex maint info selftests
+@cindex self tests
+@item maint info selftests
+List the selftests compiled in to @value{GDBN}.
@kindex maint set dwarf always-disassemble
@kindex maint show dwarf always-disassemble
memory will be used. Setting it to zero disables caching, which will
slow down @value{GDBN} startup, but reduce memory consumption.
+@kindex maint set dwarf unwinders
+@kindex maint show dwarf unwinders
+@item maint set dwarf unwinders
+@itemx maint show dwarf unwinders
+Control use of the DWARF frame unwinders.
+
+@cindex DWARF frame unwinders
+Many targets that support DWARF debugging use @value{GDBN}'s DWARF
+frame unwinders to build the backtrace. Many of these targets will
+also have a second mechanism for building the backtrace for use in
+cases where DWARF information is not available, this second mechanism
+is often an analysis of a function's prologue.
+
+In order to extend testing coverage of the second level stack
+unwinding mechanisms it is helpful to be able to disable the DWARF
+stack unwinders, this can be done with this switch.
+
+In normal use of @value{GDBN} disabling the DWARF unwinders is not
+advisable, there are cases that are better handled through DWARF than
+prologue analysis, and the debug experience is likely to be better
+with the DWARF frame unwinders enabled.
+
+If DWARF frame unwinders are not supported for a particular target
+architecture, then enabling this flag does not cause them to be used.
@kindex maint set profile
@kindex maint show profile
@cindex profiling GDB
@end enumerate
@end table
+@kindex maint set check-libthread-db
+@kindex maint show check-libthread-db
+@item maint set check-libthread-db [on|off]
+@itemx maint show check-libthread-db
+Control whether @value{GDBN} should run integrity checks on inferior
+specific thread debugging libraries as they are loaded. The default
+is not to perform such checks. If any check fails @value{GDBN} will
+unload the library and continue searching for a suitable candidate as
+described in @ref{set libthread-db-search-path}. For more information
+about the tests, see @ref{maint check libthread-db}.
+
@kindex maint space
@cindex memory used by commands
@item maint space @var{value}
is also printed. For dynamically linked executables, the name of
executable or shared library containing the symbol is printed as well.
+@kindex maint test-options
+@item maint test-options require-delimiter
+@itemx maint test-options unknown-is-error
+@itemx maint test-options unknown-is-operand
+These commands are used by the testsuite to validate the command
+options framework. The @code{require-delimiter} variant requires a
+double-dash delimiter to indicate end of options. The
+@code{unknown-is-error} and @code{unknown-is-operand} do not. The
+@code{unknown-is-error} variant throws an error on unknown option,
+while @code{unknown-is-operand} treats unknown options as the start of
+the command's operands. When run, the commands output the result of
+the processed options. When completed, the commands store the
+internal result of completion in a variable exposed by the @code{maint
+show test-options-completion-result} command.
+
+@kindex maint show test-options-completion-result
+@item maint show test-options-completion-result
+Shows the result of completing the @code{maint test-options}
+subcommands. This is used by the testsuite to validate completion
+support in the command options framework.
+
+@kindex maint set test-settings
+@kindex maint show test-settings
+@item maint set test-settings @var{kind}
+@itemx maint show test-settings @var{kind}
+These are representative commands for each @var{kind} of setting type
+@value{GDBN} supports. They are used by the testsuite for exercising
+the settings infrastructure.
+
+@kindex maint with
+@item maint with @var{setting} [@var{value}] [-- @var{command}]
+Like the @code{with} command, but works with @code{maintenance set}
+variables. This is used by the testsuite to exercise the @code{with}
+command's infrastructure.
+
@end table
The following command is useful for non-interactive invocations of
for success
@end table
+@item vMustReplyEmpty
+@cindex @samp{vMustReplyEmpty} packet
+The correct reply to an unknown @samp{v} packet is to return the empty
+string, however, some older versions of @command{gdbserver} would
+incorrectly return @samp{OK} for unknown @samp{v} packets.
+
+The @samp{vMustReplyEmpty} is used as a feature test to check how
+@command{gdbserver} handles unknown packets, it is important that this
+packet be handled in the same way as other unknown @samp{v} packets.
+If this packet is handled differently to other unknown @samp{v}
+packets then it is possile that @value{GDBN} may run into problems in
+other areas, specifically around use of @samp{vFile:setfs:}.
+
@item vRun;@var{filename}@r{[};@var{argument}@r{]}@dots{}
@cindex @samp{vRun} packet
Run the program @var{filename}, passing it each @var{argument} on its
@item X @var{len},@var{expr}
@var{len} is the length of the bytecode expression and @var{expr} is the
-actual conditional expression in bytecode form.
+actual commands expression in bytecode form.
@end table
This should only be done on targets that actually support disabling
address space randomization.
+@item QStartupWithShell:@var{value}
+@cindex startup with shell, remote request
+@cindex @samp{QStartupWithShell} packet
+On UNIX-like targets, it is possible to start the inferior using a
+shell program. This is the default behavior on both @value{GDBN} and
+@command{gdbserver} (@pxref{set startup-with-shell}). This packet is
+used to inform @command{gdbserver} whether it should start the
+inferior using a shell or not.
+
+If @var{value} is @samp{0}, @command{gdbserver} will not use a shell
+to start the inferior. If @var{value} is @samp{1},
+@command{gdbserver} will use a shell to start the inferior. All other
+values are considered an error.
+
+This packet is only available in extended mode (@pxref{extended
+mode}).
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+
+@item E @var{nn}
+An error occurred. The error number @var{nn} is given as hex digits.
+@end table
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qSupported}). This should only be done on targets that
+actually support starting the inferior using a shell.
+
+Use of this packet is controlled by the @code{set startup-with-shell}
+command; @pxref{set startup-with-shell}.
+
+@item QEnvironmentHexEncoded:@var{hex-value}
+@anchor{QEnvironmentHexEncoded}
+@cindex set environment variable, remote request
+@cindex @samp{QEnvironmentHexEncoded} packet
+On UNIX-like targets, it is possible to set environment variables that
+will be passed to the inferior during the startup process. This
+packet is used to inform @command{gdbserver} of an environment
+variable that has been defined by the user on @value{GDBN} (@pxref{set
+environment}).
+
+The packet is composed by @var{hex-value}, an hex encoded
+representation of the @var{name=value} format representing an
+environment variable. The name of the environment variable is
+represented by @var{name}, and the value to be assigned to the
+environment variable is represented by @var{value}. If the variable
+has no value (i.e., the value is @code{null}), then @var{value} will
+not be present.
+
+This packet is only available in extended mode (@pxref{extended
+mode}).
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+@end table
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qSupported}). This should only be done on targets that
+actually support passing environment variables to the starting
+inferior.
+
+This packet is related to the @code{set environment} command;
+@pxref{set environment}.
+
+@item QEnvironmentUnset:@var{hex-value}
+@anchor{QEnvironmentUnset}
+@cindex unset environment variable, remote request
+@cindex @samp{QEnvironmentUnset} packet
+On UNIX-like targets, it is possible to unset environment variables
+before starting the inferior in the remote target. This packet is
+used to inform @command{gdbserver} of an environment variable that has
+been unset by the user on @value{GDBN} (@pxref{unset environment}).
+
+The packet is composed by @var{hex-value}, an hex encoded
+representation of the name of the environment variable to be unset.
+
+This packet is only available in extended mode (@pxref{extended
+mode}).
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+@end table
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qSupported}). This should only be done on targets that
+actually support passing environment variables to the starting
+inferior.
+
+This packet is related to the @code{unset environment} command;
+@pxref{unset environment}.
+
+@item QEnvironmentReset
+@anchor{QEnvironmentReset}
+@cindex reset environment, remote request
+@cindex @samp{QEnvironmentReset} packet
+On UNIX-like targets, this packet is used to reset the state of
+environment variables in the remote target before starting the
+inferior. In this context, reset means unsetting all environment
+variables that were previously set by the user (i.e., were not
+initially present in the environment). It is sent to
+@command{gdbserver} before the @samp{QEnvironmentHexEncoded}
+(@pxref{QEnvironmentHexEncoded}) and the @samp{QEnvironmentUnset}
+(@pxref{QEnvironmentUnset}) packets.
+
+This packet is only available in extended mode (@pxref{extended
+mode}).
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+@end table
+
+This packet is not probed by default; the remote stub must request it,
+by supplying an appropriate @samp{qSupported} response
+(@pxref{qSupported}). This should only be done on targets that
+actually support passing environment variables to the starting
+inferior.
+
+@item QSetWorkingDir:@r{[}@var{directory}@r{]}
+@anchor{QSetWorkingDir packet}
+@cindex set working directory, remote request
+@cindex @samp{QSetWorkingDir} packet
+This packet is used to inform the remote server of the intended
+current working directory for programs that are going to be executed.
+
+The packet is composed by @var{directory}, an hex encoded
+representation of the directory that the remote inferior will use as
+its current working directory. If @var{directory} is an empty string,
+the remote server should reset the inferior's current working
+directory to its original, empty value.
+
+This packet is only available in extended mode (@pxref{extended
+mode}).
+
+Reply:
+@table @samp
+@item OK
+The request succeeded.
+@end table
+
@item qfThreadInfo
@itemx qsThreadInfo
@cindex list active threads, remote request
@tab @samp{-}
@tab Yes
-@item @samp{qXfer:spu:read}
-@tab No
-@tab @samp{-}
-@tab Yes
-
-@item @samp{qXfer:spu:write}
-@tab No
-@tab @samp{-}
-@tab Yes
-
@item @samp{qXfer:siginfo:read}
@tab No
@tab @samp{-}
The remote stub understands the @samp{qXfer:sdata:read} packet
(@pxref{qXfer sdata read}).
-@item qXfer:spu:read
-The remote stub understands the @samp{qXfer:spu:read} packet
-(@pxref{qXfer spu read}).
-
-@item qXfer:spu:write
-The remote stub understands the @samp{qXfer:spu:write} packet
-(@pxref{qXfer spu write}).
-
@item qXfer:siginfo:read
The remote stub understands the @samp{qXfer:siginfo:read} packet
(@pxref{qXfer siginfo read}).
by supplying an appropriate @samp{qSupported} response
(@pxref{qSupported}).
-@item qXfer:spu:read:@var{annex}:@var{offset},@var{length}
-@anchor{qXfer spu read}
-Read contents of an @code{spufs} file on the target system. The
-annex specifies which file to read; it must be of the form
-@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID
-in the target process, and @var{name} identifes the @code{spufs} file
-in that context to be accessed.
-
-This packet is not probed by default; the remote stub must request it,
-by supplying an appropriate @samp{qSupported} response
-(@pxref{qSupported}).
-
@item qXfer:threads:read::@var{offset},@var{length}
@anchor{qXfer threads read}
Access the list of threads on target. @xref{Thread List Format}. The
This packet is not probed by default; the remote stub must request it,
by supplying an appropriate @samp{qSupported} response
(@pxref{qSupported}).
-
-@item qXfer:spu:write:@var{annex}:@var{offset}:@var{data}@dots{}
-@anchor{qXfer spu write}
-Write @var{data} to an @code{spufs} file on the target system. The
-annex specifies which file to write; it must be of the form
-@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID
-in the target process, and @var{name} identifes the @code{spufs} file
-in that context to be accessed.
-
-This packet is not probed by default; the remote stub must request it,
-by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
@end table
@item qXfer:@var{object}:@var{operation}:@dots{}
<!-- .................................... .............. -->
<!-- memory-map.dtd -->
<!-- memory-map: Root element with versioning -->
-<!ELEMENT memory-map (memory | property)>
+<!ELEMENT memory-map (memory)*>
<!ATTLIST memory-map version CDATA #FIXED "1.0.0">
-<!ELEMENT memory (property)>
+<!ELEMENT memory (property)*>
<!-- memory: Specifies a memory region,
and its type, or device. -->
-<!ATTLIST memory type CDATA #REQUIRED
+<!ATTLIST memory type (ram|rom|flash) #REQUIRED
start CDATA #REQUIRED
- length CDATA #REQUIRED
- device CDATA #IMPLIED>
+ length CDATA #REQUIRED>
<!-- property: Generic attribute tag -->
<!ELEMENT property (#PCDATA | property)*>
-<!ATTLIST property name CDATA #REQUIRED>
+<!ATTLIST property name (blocksize) #REQUIRED>
@end smallexample
@node Thread List Format
the thread was last executing on. The @samp{name} attribute, if
present, specifies the human-readable name of the thread. The content
of the of @samp{thread} element is interpreted as human-readable
-auxiliary information.
+auxiliary information. The @samp{handle} attribute, if present,
+is a hex encoded representation of the thread handle.
+
@node Traceframe Info Format
@section Traceframe Info Format
@var{bitsize}. The default is @code{int}.
@item group
-The register group to which this register belongs. It must
-be either @code{general}, @code{float}, or @code{vector}. If no
-@var{group} is specified, @value{GDBN} will not display the register
-in @code{info registers}.
+The register group to which this register belongs. It can be one of the
+standard register groups @code{general}, @code{float}, @code{vector} or an
+arbitrary string. Group names should be limited to alphanumeric characters.
+If a group name is made up of multiple words the words may be separated by
+hyphens; e.g.@: @code{special-group} or @code{ultra-special-group}. If no
+@var{group} is specified, @value{GDBN} will not display the register in
+@code{info registers}.
@end table
@item int8
@itemx int16
+@itemx int24
@itemx int32
@itemx int64
@itemx int128
@item uint8
@itemx uint16
+@itemx uint24
@itemx uint32
@itemx uint64
@itemx uint128
* M68K Features::
* NDS32 Features::
* Nios II Features::
+* OpenRISC 1000 Features::
* PowerPC Features::
+* RISC-V Features::
+* RX Features::
* S/390 and System z Features::
* Sparc Features::
* TIC6x Features::
it should contain registers @samp{v0} through @samp{v31}, @samp{fpsr},
and @samp{fpcr}.
+The @samp{org.gnu.gdb.aarch64.sve} feature is optional. If present,
+it should contain registers @samp{z0} through @samp{z31}, @samp{p0}
+through @samp{p15}, @samp{ffr} and @samp{vg}.
+
+The @samp{org.gnu.gdb.aarch64.pauth} feature is optional. If present,
+it should contain registers @samp{pauth_dmask} and @samp{pauth_cmask}.
+
@node ARC Features
@subsection ARC Features
@cindex target descriptions, ARC Features
@samp{zmm16h} through @samp{zmm31h}, only valid for amd64.
@end itemize
+The @samp{org.gnu.gdb.i386.pkeys} feature is optional. It should
+describe a single register, @samp{pkru}. It is a 32-bit register
+valid for i386 and amd64.
+
@node MicroBlaze Features
@subsection MicroBlaze Features
@cindex target descriptions, MicroBlaze features
@samp{pc}, and the 16 control registers (@samp{status} through
@samp{mpuacc}).
+@node OpenRISC 1000 Features
+@subsection Openrisc 1000 Features
+@cindex target descriptions, OpenRISC 1000 features
+
+The @samp{org.gnu.gdb.or1k.group0} feature is required for OpenRISC 1000
+targets. It should contain the 32 general purpose registers (@samp{r0}
+through @samp{r31}), @samp{ppc}, @samp{npc} and @samp{sr}.
+
@node PowerPC Features
@subsection PowerPC Features
@cindex target descriptions, PowerPC features
contain registers @samp{f0} through @samp{f31} and @samp{fpscr}.
The @samp{org.gnu.gdb.power.altivec} feature is optional. It should
-contain registers @samp{vr0} through @samp{vr31}, @samp{vscr},
-and @samp{vrsave}.
+contain registers @samp{vr0} through @samp{vr31}, @samp{vscr}, and
+@samp{vrsave}. @value{GDBN} will define pseudo-registers @samp{v0}
+through @samp{v31} as aliases for the corresponding @samp{vrX}
+registers.
The @samp{org.gnu.gdb.power.vsx} feature is optional. It should
-contain registers @samp{vs0h} through @samp{vs31h}. @value{GDBN}
-will combine these registers with the floating point registers
-(@samp{f0} through @samp{f31}) and the altivec registers (@samp{vr0}
-through @samp{vr31}) to present the 128-bit wide registers @samp{vs0}
-through @samp{vs63}, the set of vector registers for POWER7.
+contain registers @samp{vs0h} through @samp{vs31h}. @value{GDBN} will
+combine these registers with the floating point registers (@samp{f0}
+through @samp{f31}) and the altivec registers (@samp{vr0} through
+@samp{vr31}) to present the 128-bit wide registers @samp{vs0} through
+@samp{vs63}, the set of vector-scalar registers for POWER7.
+Therefore, this feature requires both @samp{org.gnu.gdb.power.fpu} and
+@samp{org.gnu.gdb.power.altivec}.
The @samp{org.gnu.gdb.power.spe} feature is optional. It should
contain registers @samp{ev0h} through @samp{ev31h}, @samp{acc}, and
these to present registers @samp{ev0} through @samp{ev31} to the
user.
+The @samp{org.gnu.gdb.power.ppr} feature is optional. It should
+contain the 64-bit register @samp{ppr}.
+
+The @samp{org.gnu.gdb.power.dscr} feature is optional. It should
+contain the 64-bit register @samp{dscr}.
+
+The @samp{org.gnu.gdb.power.tar} feature is optional. It should
+contain the 64-bit register @samp{tar}.
+
+The @samp{org.gnu.gdb.power.ebb} feature is optional. It should
+contain registers @samp{bescr}, @samp{ebbhr} and @samp{ebbrr}, all
+64-bit wide.
+
+The @samp{org.gnu.gdb.power.linux.pmu} feature is optional. It should
+contain registers @samp{mmcr0}, @samp{mmcr2}, @samp{siar}, @samp{sdar}
+and @samp{sier}, all 64-bit wide. This is the subset of the isa 2.07
+server PMU registers provided by @sc{gnu}/Linux.
+
+The @samp{org.gnu.gdb.power.htm.spr} feature is optional. It should
+contain registers @samp{tfhar}, @samp{texasr} and @samp{tfiar}, all
+64-bit wide.
+
+The @samp{org.gnu.gdb.power.htm.core} feature is optional. It should
+contain the checkpointed general-purpose registers @samp{cr0} through
+@samp{cr31}, as well as the checkpointed registers @samp{clr} and
+@samp{cctr}. These registers may all be either 32-bit or 64-bit
+depending on the target. It should also contain the checkpointed
+registers @samp{ccr} and @samp{cxer}, which should both be 32-bit
+wide.
+
+The @samp{org.gnu.gdb.power.htm.fpu} feature is optional. It should
+contain the checkpointed 64-bit floating-point registers @samp{cf0}
+through @samp{cf31}, as well as the checkpointed 64-bit register
+@samp{cfpscr}.
+
+The @samp{org.gnu.gdb.power.htm.altivec} feature is optional. It
+should contain the checkpointed altivec registers @samp{cvr0} through
+@samp{cvr31}, all 128-bit wide. It should also contain the
+checkpointed registers @samp{cvscr} and @samp{cvrsave}, both 32-bit
+wide.
+
+The @samp{org.gnu.gdb.power.htm.vsx} feature is optional. It should
+contain registers @samp{cvs0h} through @samp{cvs31h}. @value{GDBN}
+will combine these registers with the checkpointed floating point
+registers (@samp{cf0} through @samp{cf31}) and the checkpointed
+altivec registers (@samp{cvr0} through @samp{cvr31}) to present the
+128-bit wide checkpointed vector-scalar registers @samp{cvs0} through
+@samp{cvs63}. Therefore, this feature requires both
+@samp{org.gnu.gdb.power.htm.altivec} and
+@samp{org.gnu.gdb.power.htm.fpu}.
+
+The @samp{org.gnu.gdb.power.htm.ppr} feature is optional. It should
+contain the 64-bit checkpointed register @samp{cppr}.
+
+The @samp{org.gnu.gdb.power.htm.dscr} feature is optional. It should
+contain the 64-bit checkpointed register @samp{cdscr}.
+
+The @samp{org.gnu.gdb.power.htm.tar} feature is optional. It should
+contain the 64-bit checkpointed register @samp{ctar}.
+
+
+@node RISC-V Features
+@subsection RISC-V Features
+@cindex target descriptions, RISC-V Features
+
+The @samp{org.gnu.gdb.riscv.cpu} feature is required for RISC-V
+targets. It should contain the registers @samp{x0} through
+@samp{x31}, and @samp{pc}. Either the architectural names (@samp{x0},
+@samp{x1}, etc) can be used, or the ABI names (@samp{zero}, @samp{ra},
+etc).
+
+The @samp{org.gnu.gdb.riscv.fpu} feature is optional. If present, it
+should contain registers @samp{f0} through @samp{f31}, @samp{fflags},
+@samp{frm}, and @samp{fcsr}. As with the cpu feature, either the
+architectural register names, or the ABI names can be used.
+
+The @samp{org.gnu.gdb.riscv.virtual} feature is optional. If present,
+it should contain registers that are not backed by real registers on
+the target, but are instead virtual, where the register value is
+derived from other target state. In many ways these are like
+@value{GDBN}s pseudo-registers, except implemented by the target.
+Currently the only register expected in this set is the one byte
+@samp{priv} register that contains the target's privilege level in the
+least significant two bits.
+
+The @samp{org.gnu.gdb.riscv.csr} feature is optional. If present, it
+should contain all of the target's standard CSRs. Standard CSRs are
+those defined in the RISC-V specification documents. There is some
+overlap between this feature and the fpu feature; the @samp{fflags},
+@samp{frm}, and @samp{fcsr} registers could be in either feature. The
+expectation is that these registers will be in the fpu feature if the
+target has floating point hardware, but can be moved into the csr
+feature if the target has the floating point control registers, but no
+other floating point hardware.
+
+@node RX Features
+@subsection RX Features
+@cindex target descriptions, RX Features
+
+The @samp{org.gnu.gdb.rx.core} feature is required for RX
+targets. It should contain the registers @samp{r0} through
+@samp{r15}, @samp{usp}, @samp{isp}, @samp{psw}, @samp{pc}, @samp{intb},
+@samp{bpsw}, @samp{bpc}, @samp{fintv}, @samp{fpsw}, and @samp{acc}.
+
@node S/390 and System z Features
@subsection S/390 and System z Features
@cindex target descriptions, S/390 features
contain the 128-bit wide vector registers @samp{v16} through
@samp{v31}.
+The @samp{org.gnu.gdb.s390.gs} feature is optional. It should contain
+the 64-bit wide guarded-storage-control registers @samp{gsd},
+@samp{gssm}, and @samp{gsepla}.
+
+The @samp{org.gnu.gdb.s390.gsbc} feature is optional. It should contain
+the 64-bit wide guarded-storage broadcast control registers
+@samp{bc_gsd}, @samp{bc_gssm}, and @samp{bc_gsepla}.
+
@node Sparc Features
@subsection Sparc Features
@cindex target descriptions, sparc32 features
* gdbserver man:: Remote Server for the GNU Debugger man page
* gcore man:: Generate a core file of a running program
* gdbinit man:: gdbinit scripts
+* gdb-add-index man:: Add index files to speed up GDB
@end menu
@node gdb man
gdb program core
@end smallexample
-You can, instead, specify a process ID as a second argument, if you want
-to debug a running process:
+You can, instead, specify a process ID as a second argument or use option
+@code{-p}, if you want to debug a running process:
@smallexample
gdb program 1234
@end smallexample
@noindent
-would attach @value{GDBN} to process @code{1234} (unless you also have a file
-named @file{1234}; @value{GDBN} does check for a core file first).
-With option @option{-p} you can omit the @var{program} filename.
+would attach @value{GDBN} to process @code{1234}. With option @option{-p} you
+can omit the @var{program} filename.
Here are some of the most frequently needed @value{GDBN} commands:
@end ifset
You need an unstripped copy of the target program on your host system, since
-@value{GDBN} needs to examine it's symbol tables and such. Start up @value{GDBN} as you normally
+@value{GDBN} needs to examine its symbol tables and such. Start up @value{GDBN} as you normally
would, with the target program as the first argument. (You may need to use the
@option{--baud} option if the serial line is running at anything except 9600 baud.)
That is @code{gdb TARGET-PROG}, or @code{gdb --baud BAUD TARGET-PROG}. After that, the only
This option is intended for @code{gdbserver} development and for bug reports to
the developers.
+@item --debug-file=@var{filename}
+Instruct @code{gdbserver} to send any debug output to the given @var{filename}.
+This option is intended for @code{gdbserver} development and for bug reports to
+the developers.
+
@item --debug-format=option1@r{[},option2,...@r{]}
Instruct @code{gdbserver} to include extra information in each line
of debugging output.
@format
@c man begin SYNOPSIS gcore
-gcore [-o @var{filename}] @var{pid}
+gcore [-a] [-o @var{prefix}] @var{pid1} [@var{pid2}...@var{pidN}]
@c man end
@end format
@c man begin DESCRIPTION gcore
-Generate a core dump of a running program with process ID @var{pid}.
-Produced file is equivalent to a kernel produced core file as if the process
-crashed (and if @kbd{ulimit -c} were used to set up an appropriate core dump
-limit). Unlike after a crash, after @command{gcore} the program remains
-running without any change.
+Generate core dumps of one or more running programs with process IDs
+@var{pid1}, @var{pid2}, etc. A core file produced by @command{gcore}
+is equivalent to one produced by the kernel when the process crashes
+(and when @kbd{ulimit -c} was used to set up an appropriate core dump
+limit). However, unlike after a crash, after @command{gcore} finishes
+its job the program remains running without any change.
@c man end
@c man begin OPTIONS gcore
@table @env
-@item -o @var{filename}
-The optional argument
-@var{filename} specifies the file name where to put the core dump.
-If not specified, the file name defaults to @file{core.@var{pid}},
-where @var{pid} is the running program process ID.
+@item -a
+Dump all memory mappings. The actual effect of this option depends on
+the Operating System. On @sc{gnu}/Linux, it will disable
+@code{use-coredump-filter} (@pxref{set use-coredump-filter}) and
+enable @code{dump-excluded-mappings} (@pxref{set
+dump-excluded-mappings}).
+
+@item -o @var{prefix}
+The optional argument @var{prefix} specifies the prefix to be used
+when composing the file names of the core dumps. The file name is
+composed as @file{@var{prefix}.@var{pid}}, where @var{pid} is the
+process ID of the running program being analyzed by @command{gcore}.
+If not specified, @var{prefix} defaults to @var{gcore}.
@end table
@c man end
@value{SYSTEM_GDBINIT}
@end ifset
+@ifset SYSTEM_GDBINIT_DIR
+@value{SYSTEM_GDBINIT_DIR}/*
+@end ifset
+
~/.gdbinit
./.gdbinit
the @value{GDBN} manual in node @code{System-wide configuration}
-- shell command @code{info -f gdb -n 'System-wide configuration'}.
@end ifset
+@ifset SYSTEM_GDBINIT_DIR
+@item @value{SYSTEM_GDBINIT_DIR}
+@end ifset
+@ifclear SYSTEM_GDBINIT_DIR
+@item (not enabled with @code{--with-system-gdbinit-dir} during compilation)
+@end ifclear
+System-wide initialization directory. All files in this directory are
+executed on startup unless user specified @value{GDBN} option @code{-nx} or
+@code{-n}, as long as they have a recognized file extension.
+See more in
+@ifset man
+the @value{GDBN} manual in node @code{System-wide configuration}
+-- shell command @code{info -f gdb -n 'System-wide configuration'}.
+@end ifset
@ifclear man
@ref{System-wide configuration}.
@end ifclear
@end ifset
@c man end
+@node gdb-add-index man
+@heading gdb-add-index
+@pindex gdb-add-index
+@anchor{gdb-add-index}
+
+@c man title gdb-add-index Add index files to speed up GDB
+
+@c man begin SYNOPSIS gdb-add-index
+gdb-add-index @var{filename}
+@c man end
+
+@c man begin DESCRIPTION gdb-add-index
+When @value{GDBN} finds a symbol file, it scans the symbols in the
+file in order to construct an internal symbol table. This lets most
+@value{GDBN} operations work quickly--at the cost of a delay early on.
+For large programs, this delay can be quite lengthy, so @value{GDBN}
+provides a way to build an index, which speeds up startup.
+
+To determine whether a file contains such an index, use the command
+@kbd{readelf -S filename}: the index is stored in a section named
+@code{.gdb_index}. The index file can only be produced on systems
+which use ELF binaries and DWARF debug information (i.e., sections
+named @code{.debug_*}).
+
+@command{gdb-add-index} uses @value{GDBN} and @command{objdump} found
+in the @env{PATH} environment variable. If you want to use different
+versions of these programs, you can specify them through the
+@env{GDB} and @env{OBJDUMP} environment variables.
+
+See more in
+@ifset man
+the @value{GDBN} manual in node @code{Index Files}
+-- shell command @kbd{info -f gdb -n "Index Files"}.
+@end ifset
+@ifclear man
+@ref{Index Files}.
+@end ifclear
+@c man end
+
+@c man begin SEEALSO gdb-add-index
+@ifset man
+The full documentation for @value{GDBN} is maintained as a Texinfo manual.
+If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
+documentation are properly installed at your site, the command
+
+@smallexample
+info gdb
+@end smallexample
+
+should give you access to the complete manual.
+
+@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
+Richard M. Stallman and Roland H. Pesch, July 1991.
+@end ifset
+@c man end
+
@include gpl.texi
@node GNU Free Documentation License
projects / deliverable / binutils-gdb.git / blobdiff