\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988--2022 Free Software Foundation, Inc.
+@c Copyright (C) 1988--2023 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-2022 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2023 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-2022 Free Software Foundation, Inc.
+Copyright (C) 1988-2023 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
* Configurations:: Configuration-specific information
* Controlling GDB:: Controlling @value{GDBN}
* Extending GDB:: Extending @value{GDBN}
-* Interpreters:: Command Interpreters
+* Interpreters:: Command Interpreters
* TUI:: @value{GDBN} Text User Interface
* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
* GDB/MI:: @value{GDBN}'s Machine Interface.
@end ifclear
* In Memoriam:: In Memoriam
* Formatting Documentation:: How to format and print @value{GDBN} documentation
-* Installing GDB:: Installing GDB
+* Installing GDB:: Installing @value{GDBN}
* Maintenance Commands:: Maintenance Commands
* Remote Protocol:: GDB Remote Serial Protocol
-* Agent Expressions:: The GDB Agent Expression Mechanism
+* Agent Expressions:: The @value{GDBN} Agent Expression Mechanism
* Target Descriptions:: How targets can describe themselves to
@value{GDBN}
* Operating System Information:: Getting additional information from
the operating system
-* Trace File Format:: GDB trace file format
+* Trace File Format:: @value{GDBN} trace file format
* Index Section Format:: .gdb_index section format
* Debuginfod:: Download debugging resources with @code{debuginfod}
-* Man Pages:: Manual pages
-* Copying:: GNU General Public License says
- how you can copy and share GDB
+* Man Pages:: Manual pages
+* Copying:: GNU General Public License says
+ how you can copy and share @value{GDBN}
* GNU Free Documentation License:: The license for this documentation
* Concept Index:: Index of @value{GDBN} concepts
* Command and Variable Index:: Index of @value{GDBN} commands, variables,
- functions, and Python data types
+ functions, and Python data types
@end menu
@end ifnottex
such as for most embedded targets, then it will complain about a second
argument and ignore it.
+For the @samp{-s}, @samp{-e}, and @samp{-se} options, and their long
+form equivalents, the method used to search the file system for the
+symbol and/or executable file is the same as that used by the
+@code{file} command. @xref{Files, ,file}.
+
Many options have both long and short forms; both are shown in the
following list. @value{GDBN} also recognizes the long forms if you truncate
them, so long as enough of the option is present to be unambiguous.
@cindex shell escape
@item shell @var{command-string}
@itemx !@var{command-string}
-Invoke a standard shell to execute @var{command-string}.
+Invoke a shell to execute @var{command-string}.
Note that no space is needed between @code{!} and @var{command-string}.
On GNU and Unix systems, the environment variable @env{SHELL}, if it
exists, determines which shell to run. Otherwise @value{GDBN} uses
@file{cmd.exe} on MS-Windows, @file{COMMAND.COM} on MS-DOS, etc.).
@end table
+You may also invoke shell commands from expressions, using the
+@code{$_shell} convenience function. @xref{$_shell convenience
+function}.
+
The utility @code{make} is often needed in development environments.
You do not have to use the @code{shell} command for this purpose in
@value{GDBN}:
Example:
@smallexample
@group
-(gdb) p var
+(@value{GDBP}) p var
$1 = @{
black = 144,
red = 233,
@}
@end group
@group
-(gdb) pipe p var|wc
+(@value{GDBP}) pipe p var|wc
7 19 80
-(gdb) |p var|wc -l
+(@value{GDBP}) |p var|wc -l
7
@end group
@group
-(gdb) p /x var
+(@value{GDBP}) p /x var
$4 = @{
black = 0x90,
red = 0xe9,
blue = 0x262,
white = 0x3db
@}
-(gdb) ||grep red
+(@value{GDBP}) ||grep red
red => 0xe9,
@end group
@group
-(gdb) | -d ! echo this contains a | char\n ! sed -e 's/|/PIPE/'
+(@value{GDBP}) | -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/'
+(@value{GDBP}) | -d xxx echo this contains a | char!\n xxx sed -e 's/|/PIPE/'
this contains a PIPE char!
-(gdb)
+(@value{GDBP})
@end group
@end smallexample
@end table
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
+(@value{GDBP}) set print elements 10
+(@value{GDBP}) print some_array
$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@}
@end smallexample
print} subcommands. @xref{print options}. The example above could be
rewritten as:
@smallexample
-(@value{GDBN}) print -elements 10 -- some_array
+(@value{GDBP}) print -elements 10 -- some_array
$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@}
@end smallexample
For example, the command
@smallexample
-(@value{GDBN}) with print array on -- print some_array
+(@value{GDBP}) 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
+(@value{GDBP}) set print array on
+(@value{GDBP}) print some_array
+(@value{GDBP}) set print array off
@end smallexample
The @code{with} command is particularly useful when you want to
defined in Python or Guile. @xref{Extending GDB,, Extending GDB}.
@smallexample
-(@value{GDBN}) with print pretty on -- my_complex_command
+(@value{GDBP}) with print pretty on -- my_complex_command
@end smallexample
To change several settings for the same command, you can nest
@c If texinfo enhancements make it unnecessary, it would be nice to
@c replace " @key" by "@key" in the following...
@smallexample
-(@value{GDBP}) info bre @key{TAB}
+(@value{GDBP}) info bre@key{TAB}
@end smallexample
@noindent
example:
@smallexample
-(@value{GDBP}) b make_ @key{TAB}
+(@value{GDBP}) b make_@key{TAB}
@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see:
make_a_section_from_file make_environ
make_abs_section make_function_type
partial input (@samp{b make_} in the example) so you can finish the
command.
+If the command you are trying to complete expects either a keyword or a
+number to follow, then @samp{NUMBER} will be shown among the available
+completions, for example:
+
+@smallexample
+(@value{GDBP}) print -elements @key{TAB}@key{TAB}
+NUMBER unlimited
+(@value{GDBP}) print -elements@tie{}
+@end smallexample
+
+@noindent
+Here, the option expects a number (e.g., @code{100}), not literal
+@code{NUMBER}. Such metasyntactical arguments are always presented in
+uppercase.
+
If you just want to see the list of alternatives in the first place, you
can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?}
means @kbd{@key{META} ?}. You can type this either by holding down a
when you press @key{TAB} or @kbd{M-?} to request word completion:
@smallexample
-(@value{GDBP}) p 'func< @kbd{M-?}
+(@value{GDBP}) p 'func<@kbd{M-?}
func<int>() func<float>()
(@value{GDBP}) p 'func<
@end smallexample
-When setting breakpoints however (@pxref{Specify Location}), you don't
+When setting breakpoints however (@pxref{Location Specifications}), 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 func< @kbd{M-?}
+(@value{GDBP}) b func<@kbd{M-?}
func<int>() func<float>()
(@value{GDBP}) b func<
@end smallexample
that takes a @code{float} parameter, @code{name(float)}.
@smallexample
-(@value{GDBP}) b bubble( @kbd{M-?}
+(@value{GDBP}) b bubble(@kbd{M-?}
bubble(int) bubble(double)
-(@value{GDBP}) b bubble(dou @kbd{M-?}
+(@value{GDBP}) b bubble(dou@kbd{M-?}
bubble(double)
@end smallexample
@smallexample
(@value{GDBP}) print -@key{TAB}@key{TAB}
--address -max-depth -pretty -symbol
--array -memory-tag-violations -raw-values -union
--array-indexes -null-stop -repeats -vtbl
--elements -object -static-members
+-address -max-depth -object -static-members
+-array -memory-tag-violations -pretty -symbol
+-array-indexes -nibbles -raw-values -union
+-elements -null-stop -repeats -vtbl
@end smallexample
Completion will in some cases guide you with a suggestion of what kind
NUMBER unlimited
@end smallexample
+@noindent
Here, the option expects a number (e.g., @code{100}), not literal
@code{NUMBER}. Such metasyntactical arguments are always presented in
uppercase.
the command name and all its aliases separated by commas.
This first line will be followed by the full definition of all aliases
having default arguments.
+When asking the help for an alias, the documentation for the aliased
+command is shown.
+
+A user-defined alias can optionally be documented using the
+@code{document} command (@pxref{Define, document}). @value{GDBN} then
+considers this alias as different from the aliased command: this alias
+is not listed in the aliased command help output, and asking help for
+this alias will show the documentation provided for the alias instead of
+the documentation of the aliased command.
@kindex apropos
@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
+commands and aliases, and their documentation, for the regular expression specified in
@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
You can now simply switch focus to inferior 2 and run it.
+@anchor{remove_inferiors_cli}
@kindex remove-inferiors
@item remove-inferiors @var{infno}@dots{}
Removes the inferior or inferiors @var{infno}@dots{}. It is not
the name of the executable loaded into the program space, with e.g.,
the @code{file} command.
+@item
+the name of the core file loaded into the program space, with e.g.,
+the @code{core-file} command.
+
@end enumerate
@noindent
@smallexample
(@value{GDBP}) maint info program-spaces
- Id Executable
+ Id Executable Core File
* 1 hello
2 goodbye
Bound inferiors: ID 1 (process 21561)
@smallexample
(@value{GDBP}) maint info program-spaces
- Id Executable
+ Id Executable Core File
* 1 vfork-test
Bound inferiors: ID 2 (process 18050), ID 1 (process 18045)
@end smallexample
@samp{$_gthread} contain, respectively, the per-inferior thread number
and the global thread number of the current thread. You may find this
useful in writing breakpoint conditional expressions, command scripts,
-and so forth. @xref{Convenience Vars,, Convenience Variables}, for
-general information on convenience variables.
+and so forth. The convenience variable @samp{$_inferior_thread_count}
+contains the number of live threads in the current inferior.
+@xref{Convenience Vars,, Convenience Variables}, for general
+information on convenience variables.
+
+When running in non-stop mode (@pxref{Non-Stop Mode}), where new
+threads can be created, and existing threads exit, at any time,
+@samp{$_inferior_thread_count} could return a different value each
+time it is evaluated.
If @value{GDBN} detects the program is multi-threaded, it augments the
usual message about stopping at a breakpoint with the ID and name of
is the LWP id.
@smallexample
-(@value{GDBN}) thread find 26688
+(@value{GDBP}) thread find 26688
Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)'
-(@value{GDBN}) info thread 4
+(@value{GDBP}) info thread 4
Id Target Id Frame
4 Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select ()
@end smallexample
@smallexample
(@value{GDBP}) info inferiors
-(gdb) info inferior
+(@value{GDBP}) info inferior
Id Description Executable
* 1 <null> prog1
(@value{GDBP}) run
@cindex latest breakpoint
Breakpoints are set with the @code{break} command (abbreviated
@code{b}). The debugger convenience variable @samp{$bpnum} records the
-number of the breakpoint you've set most recently; see @ref{Convenience
-Vars,, Convenience Variables}, for a discussion of what you can do with
-convenience variables.
+number of the breakpoint you've set most recently:
+@smallexample
+(gdb) b main
+Breakpoint 1 at 0x11c6: file zeoes.c, line 24.
+(gdb) p $bpnum
+$1 = 1
+@end smallexample
+
+A breakpoint may be mapped to multiple code locations for example with
+inlined functions, Ada generics, C@t{++} templates or overloaded function names.
+@value{GDBN} then indicates the number of code locations in the breakpoint
+command output:
+@smallexample
+(gdb) b some_func
+Breakpoint 2 at 0x1179: some_func. (3 locations)
+(gdb) p $bpnum
+$2 = 2
+(gdb)
+@end smallexample
+
+@vindex $_hit_bpnum@r{, convenience variable}
+@vindex $_hit_locno@r{, convenience variable}
+When your program stops on a breakpoint, the convenience variables
+@samp{$_hit_bpnum} and @samp{$_hit_locno} are respectively set to the number of
+the encountered breakpoint and the number of the breakpoint's code location:
+@smallexample
+Thread 1 "zeoes" hit Breakpoint 2.1, some_func () at zeoes.c:8
+8 printf("some func\n");
+(gdb) p $_hit_bpnum
+$5 = 2
+(gdb) p $_hit_locno
+$6 = 1
+(gdb)
+@end smallexample
+
+Note that @samp{$_hit_bpnum} and @samp{$bpnum} are not equivalent:
+@samp{$_hit_bpnum} is set to the breakpoint number @b{last hit}, while
+@samp{$bpnum} is set to the breakpoint number @b{last set}.
+
+
+If the encountered breakpoint has only one code location, @samp{$_hit_locno}
+is set to 1:
+@smallexample
+Breakpoint 1, main (argc=1, argv=0x7fffffffe018) at zeoes.c:24
+24 if (argc > 1)
+(gdb) p $_hit_bpnum
+$3 = 1
+(gdb) p $_hit_locno
+$4 = 1
+(gdb)
+@end smallexample
+
+The @samp{$_hit_bpnum} and @samp{$_hit_locno} variables can typically be used
+in a breakpoint command list.
+(@pxref{Break Commands, ,Breakpoint Command Lists}). For example, as
+part of the breakpoint command list, you can disable completely the
+encountered breakpoint using @kbd{disable $_hit_bpnum} or disable the
+specific encountered breakpoint location using
+@kbd{disable $_hit_bpnum.$_hit_locno}.
+If a breakpoint has only one location, @samp{$_hit_locno} is set to 1
+and the commands @kbd{disable $_hit_bpnum} and
+@kbd{disable $_hit_bpnum.$_hit_locno} both disable the breakpoint.
+
+You can also define aliases to easily disable the last hit location or
+last hit breakpoint:
+@smallexample
+(gdb) alias lld = disable $_hit_bpnum.$_hit_locno
+(gdb) alias lbd = disable $_hit_bpnum
+@end smallexample
@table @code
-@item break @var{location}
-Set a breakpoint at the given @var{location}, which can specify a
-function name, a line number, or an address of an instruction.
-(@xref{Specify Location}, for a list of all the possible ways to
-specify a @var{location}.) The breakpoint will stop your program just
-before it executes any of the code in the specified @var{location}.
+@item break @var{locspec}
+Set a breakpoint at all the code locations in your program that result
+from resolving the given @var{locspec}. @var{locspec} can specify a
+function name, a line number, an address of an instruction, and more.
+@xref{Location Specifications}, for the various forms of
+@var{locspec}. The breakpoint will stop your program just before it
+executes the instruction at the address of any of the breakpoint's
+code locations.
-When using source languages that permit overloading of symbols, such as
-C@t{++}, a function name may refer to more than one possible place to break.
-@xref{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of
-that situation.
+When using source languages that permit overloading of symbols, such
+as C@t{++}, a function name may refer to more than one symbol, and
+thus more than one place to break. @xref{Ambiguous
+Expressions,,Ambiguous Expressions}, for a discussion of that
+situation.
It is also possible to insert a breakpoint that will stop the program
only if a specific thread (@pxref{Thread-Specific Breakpoints})
@cindex multiple locations, breakpoints
@cindex breakpoints, multiple locations
-It is possible that a breakpoint corresponds to several locations
-in your program. Examples of this situation are:
-
-@itemize @bullet
-@item
-Multiple functions in the program may have the same name.
-
-@item
-For a C@t{++} constructor, the @value{NGCC} compiler generates several
-instances of the function body, used in different cases.
-
-@item
-For a C@t{++} template function, a given line in the function can
-correspond to any number of instantiations.
-
-@item
-For an inlined function, a given source line can correspond to
-several places where that function is inlined.
-@end itemize
-
-In all those cases, @value{GDBN} will insert a breakpoint at all
-the relevant locations.
-
-A breakpoint with multiple locations is displayed in the breakpoint
-table using several rows---one header row, followed by one row for
-each breakpoint location. The header row has @samp{<MULTIPLE>} in the
-address column. The rows for individual locations contain the actual
-addresses for locations, and show the functions to which those
-locations belong. The number column for a location is of the form
+It is possible that a single logical breakpoint is set at several code
+locations in your program. @xref{Location Specifications}, for
+examples.
+
+A breakpoint with multiple code locations is displayed in the
+breakpoint table using several rows---one header row, followed by one
+row for each code location. The header row has @samp{<MULTIPLE>} in
+the address column. Each code location row contains the actual
+address, source file, source line and function of its code location.
+The number column for a code location is of the form
@var{breakpoint-number}.@var{location-number}.
For example:
Disabling or enabling the parent breakpoint (@pxref{Disabling}) affects
all of the locations that belong to that breakpoint.
+Locations that are enabled while their parent breakpoint is disabled
+won't trigger a break, and are denoted by @code{y-} in the @code{Enb}
+column. For example:
+
+@smallexample
+(@value{GDBP}) info breakpoints
+Num Type Disp Enb Address What
+1 breakpoint keep n <MULTIPLE>
+1.1 y- 0x00000000000011b6 in ...
+1.2 y- 0x00000000000011c2 in ...
+1.3 n 0x00000000000011ce in ...
+@end smallexample
+
@cindex pending breakpoints
It's quite common to have a breakpoint inside a shared library.
Shared libraries can be loaded and unloaded explicitly,
enable and disable them and perform other breakpoint operations.
@value{GDBN} provides some additional commands for controlling what
-happens when the @samp{break} command cannot resolve breakpoint
-address specification to an address:
+happens when the @samp{break} command cannot resolve the location spec
+to any code location in your program (@pxref{Location
+Specifications}):
@kindex set breakpoint pending
@kindex show breakpoint pending
@table @code
@item set breakpoint pending auto
-This is the default behavior. When @value{GDBN} cannot find the breakpoint
-location, it queries you whether a pending breakpoint should be created.
+This is the default behavior. When @value{GDBN} cannot resolve the
+location spec, it queries you whether a pending breakpoint should be
+created.
@item set breakpoint pending on
-This indicates that an unrecognized breakpoint location should automatically
-result in a pending breakpoint being created.
+This indicates that when @value{GDBN} cannot resolve the location
+spec, it should create a pending breakpoint without confirmation.
@item set breakpoint pending off
-This indicates that pending breakpoints are not to be created. Any
-unrecognized breakpoint location results in an error. This setting does
-not affect any pending breakpoints previously created.
+This indicates that pending breakpoints are not to be created. If
+@value{GDBN} cannot resolve the location spec, it aborts the
+breakpoint creation with an error. This setting does not affect any
+pending breakpoints previously created.
@item show breakpoint pending
Show the current behavior setting for creating pending breakpoints.
@end table
The settings above only affect the @code{break} command and its
-variants. Once breakpoint is set, it will be automatically updated
+variants. Once a breakpoint is set, it will be automatically updated
as shared libraries are loaded and unloaded.
@cindex automatic hardware breakpoints
the innermost frame is selected, this is a good way to delete a
breakpoint where your program just stopped.
-@item clear @var{location}
-Delete any breakpoints set at the specified @var{location}.
-@xref{Specify Location}, for the various forms of @var{location}; the
-most useful ones are listed below:
+@item clear @var{locspec}
+Delete any breakpoint with a code location that corresponds to
+@var{locspec}. @xref{Location Specifications}, for the various forms
+of @var{locspec}. Which code locations correspond to @var{locspec}
+depends on the form used in the location specification @var{locspec}:
@table @code
-@item clear @var{function}
-@itemx clear @var{filename}:@var{function}
-Delete any breakpoints set at entry to the named @var{function}.
+@item @var{linenum}
+@itemx @var{filename}:@var{linenum}
+@itemx -line @var{linenum}
+@itemx -source @var{filename} -line @var{linenum}
+If @var{locspec} specifies a line number, with or without a file name,
+the command deletes any breakpoint with a code location that is at or
+within the specified line @var{linenum} in files that match the
+specified @var{filename}. If @var{filename} is omitted, it defaults
+to the current source file.
+
+@item *@var{address}
+If @var{locspec} specifies an address, the command deletes any
+breakpoint with a code location that is at the given @var{address}.
-@item clear @var{linenum}
-@itemx clear @var{filename}:@var{linenum}
-Delete any breakpoints set at or within the code of the specified
-@var{linenum} of the specified @var{filename}.
+@item @var{function}
+@itemx -function @var{function}
+If @var{locspec} specifies a function, the command deletes any
+breakpoint with a code location that is at the entry to any function
+whose name matches @var{function}.
@end table
+Ambiguity in names of files and functions can be resolved as described
+in @ref{Location Specifications}.
+
@cindex delete breakpoints
@kindex delete
@kindex d @r{(@code{delete})}
Pressing @key{RET} as a means of repeating the last @value{GDBN} command is
disabled within a @var{command-list}.
+Inside a command list, you can use the command
+@kbd{disable $_hit_bpnum} to disable the encountered breakpoint.
+
+If your breakpoint has several code locations, the command
+@kbd{disable $_hit_bpnum.$_hit_locno} will disable the specific breakpoint
+code location encountered. If the breakpoint has only one location,
+this command will disable the encountered breakpoint.
+
You can use breakpoint commands to start your program up again. Simply
use the @code{continue} command, or @code{step}, or any other command
that resumes execution.
@table @code
@kindex dprintf
-@item dprintf @var{location},@var{template},@var{expression}[,@var{expression}@dots{}]
-Whenever execution reaches @var{location}, print the values of one or
-more @var{expressions} under the control of the string @var{template}.
-To print several values, separate them with commas.
+@item dprintf @var{locspec},@var{template},@var{expression}[,@var{expression}@dots{}]
+Whenever execution reaches a code location that results from resolving
+@var{locspec}, print the values of one or more @var{expressions} under
+the control of the string @var{template}. To print several values,
+separate them with commas.
@item set dprintf-style @var{style}
Set the dprintf output to be handled in one of several different
you could do the following:
@example
-(gdb) set dprintf-style call
-(gdb) set dprintf-function fprintf
-(gdb) set dprintf-channel mylog
-(gdb) dprintf 25,"at line 25, glob=%d\n",glob
+(@value{GDBP}) set dprintf-style call
+(@value{GDBP}) set dprintf-function fprintf
+(@value{GDBP}) set dprintf-channel mylog
+(@value{GDBP}) dprintf 25,"at line 25, glob=%d\n",glob
Dprintf 1 at 0x123456: file main.c, line 25.
-(gdb) info break
+(@value{GDBP}) info break
1 dprintf keep y 0x00123456 in main at main.c:25
call (void) fprintf (mylog,"at line 25, glob=%d\n",glob)
continue
-(gdb)
+(@value{GDBP})
@end example
Note that the @code{info break} displays the dynamic printf commands
You can enable (or disable) one or more probes using the following
commands, with optional arguments:
+@anchor{enable probes}
@table @code
@kindex enable probes
@item enable probes @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]}
instruction stepping, and hence is slower than @code{until} with an
argument.
-@item until @var{location}
-@itemx u @var{location}
-Continue running your program until either the specified @var{location} is
-reached, or the current stack frame returns. The location is any of
-the forms described in @ref{Specify Location}.
+@item until @var{locspec}
+@itemx u @var{locspec}
+Continue running your program until either it reaches a code location
+that results from resolving @var{locspec}, or the current stack frame
+returns. @var{locspec} is any of the forms described in @ref{Location
+Specifications}.
This form of the command uses temporary breakpoints, and
hence is quicker than @code{until} without an argument. The specified
location is actually reached only if it is in the current frame. This
@end smallexample
-@kindex advance @var{location}
-@item advance @var{location}
-Continue running the program up to the given @var{location}. An argument is
-required, which should be of one of the forms described in
-@ref{Specify Location}.
-Execution will also stop upon exit from the current stack
-frame. This command is similar to @code{until}, but @code{advance} will
-not skip over recursive function calls, and the target location doesn't
-have to be in the same frame as the current one.
+@kindex advance @var{locspec}
+@item advance @var{locspec}
+Continue running your program until either it reaches a code location
+that results from resolving @var{locspec}, or the current stack frame
+returns. @var{locspec} is any of the forms described in @ref{Location
+Specifications}. This command is similar to @code{until}, but
+@code{advance} will not skip over recursive function calls, and the
+target code location doesn't have to be in the same frame as the
+current one.
@kindex stepi
@code{foo}.
Functions may be skipped by providing either a function name, linespec
-(@pxref{Specify Location}), regular expression that matches the function's
+(@pxref{Location Specifications}), regular expression that matches the function's
name, file name or a @code{glob}-style pattern that matches the file name.
On Posix systems the form of the regular expression is
over when stepping.
@smallexample
-(gdb) skip -gfi utils/*.c
+(@value{GDBP}) skip -gfi utils/*.c
@end smallexample
@item -function @var{linespec}
@itemx -fu @var{linespec}
Functions named by @var{linespec} or the function containing the line
named by @var{linespec} will be skipped over when stepping.
-@xref{Specify Location}.
+@xref{Location Specifications}.
@item -rfunction @var{regexp}
@itemx -rfu @var{regexp}
regular expression makes this easier.
@smallexample
-(gdb) skip -rfu ^std::(allocator|basic_string)<.*>::~?\1 *\(
+(@value{GDBP}) skip -rfu ^std::(allocator|basic_string)<.*>::~?\1 *\(
@end smallexample
If you want to skip every templated C@t{++} constructor and destructor
in the @code{std} namespace you can do:
@smallexample
-(gdb) skip -rfu ^std::([a-zA-z0-9_]+)<.*>::~?\1 *\(
+(@value{GDBP}) skip -rfu ^std::([a-zA-z0-9_]+)<.*>::~?\1 *\(
@end smallexample
@end table
@item skip function @r{[}@var{linespec}@r{]}
After running this command, the function named by @var{linespec} or the
function containing the line named by @var{linespec} will be skipped over when
-stepping. @xref{Specify Location}.
+stepping. @xref{Location Specifications}.
If you do not specify @var{linespec}, the function you're currently debugging
will be skipped.
will be skipped over when stepping.
@smallexample
-(gdb) skip file boring.c
+(@value{GDBP}) skip file boring.c
File boring.c will be skipped when stepping.
@end smallexample
for details about this command.
@kindex handle
-@item handle @var{signal} @r{[}@var{keywords}@dots{}@r{]}
-Change the way @value{GDBN} handles signal @var{signal}. The @var{signal}
-can be the number of a signal or its name (with or without the
-@samp{SIG} at the beginning); a list of signal numbers of the form
-@samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the
-known signals. Optional arguments @var{keywords}, described below,
-say what change to make.
+@item handle @var{signal} @r{[} @var{signal} @dots{} @r{]} @r{[}@var{keywords}@dots{}@r{]}
+Change the way @value{GDBN} handles each @var{signal}. Each
+@var{signal} can be the number of a signal or its name (with or
+without the @samp{SIG} at the beginning); a list of signal numbers of
+the form @samp{@var{low}-@var{high}}; or the word @samp{all}, meaning
+all the known signals, except @code{SIGINT} and @code{SIGTRAP}, which
+are used by @value{GDBN}. Optional argument @var{keywords}, described
+below, say what changes to make to all of the specified signals.
@end table
@c @group
you examine the stopped thread in the debugger.
@menu
-* All-Stop Mode:: All threads stop when GDB takes control
-* Non-Stop Mode:: Other threads continue to execute
-* Background Execution:: Running your program asynchronously
-* Thread-Specific Breakpoints:: Controlling breakpoints
-* Interrupted System Calls:: GDB may interfere with system calls
+* All-Stop Mode:: All threads stop when GDB takes control
+* Non-Stop Mode:: Other threads continue to execute
+* Background Execution:: Running your program asynchronously
+* Thread-Specific Breakpoints:: Controlling breakpoints
+* Interrupted System Calls:: GDB may interfere with system calls
* Observer Mode:: GDB does not alter program behavior
@end menu
message such as @samp{[Switching to Thread @var{n}]} to identify the
thread.
+@anchor{set scheduler-locking}
+
On some OSes, you can modify @value{GDBN}'s default behavior by
locking the OS scheduler to allow only a single thread to run.
@cindex scheduler locking mode
@cindex lock scheduler
Set the scheduler locking mode. It applies to normal execution,
-record mode, and replay mode. If it is @code{off}, then there is no
-locking and any thread may run at any time. If @code{on}, then only
-the current thread may run when the inferior is resumed. The
-@code{step} mode optimizes for single-stepping; it prevents other
-threads from preempting the current thread while you are stepping, so
-that the focus of debugging does not change unexpectedly. Other
-threads never get a chance to run when you step, and they are
-completely free to run when you use commands like @samp{continue},
-@samp{until}, or @samp{finish}. However, unless another thread hits a
-breakpoint during its timeslice, @value{GDBN} does not change the
-current thread away from the thread that you are debugging. The
-@code{replay} mode behaves like @code{off} in record mode and like
-@code{on} in replay mode.
+record mode, and replay mode. @var{mode} can be one of
+the following:
+
+@table @code
+@item off
+There is no locking and any thread may run at any time.
+
+@item on
+Only the current thread may run when the inferior is resumed.
+
+@item step
+Behaves like @code{on} when stepping, and @code{off} otherwise.
+Threads other than the current never get a chance to run when you
+step, and they are completely free to run when you use commands like
+@samp{continue}, @samp{until}, or @samp{finish}.
+
+This mode optimizes for single-stepping; it prevents other threads
+from preempting the current thread while you are stepping, so that the
+focus of debugging does not change unexpectedly. However, unless
+another thread hits a breakpoint during its timeslice, @value{GDBN}
+does not change the current thread away from the thread that you are
+debugging.
+
+@item replay
+Behaves like @code{on} in replay mode, and @code{off} in either record
+mode or during normal execution. This is the default mode.
+@end table
@item show scheduler-locking
Display the current scheduler locking mode.
@cindex breakpoints and threads
@cindex thread breakpoints
@kindex break @dots{} thread @var{thread-id}
-@item break @var{location} thread @var{thread-id}
-@itemx break @var{location} thread @var{thread-id} if @dots{}
-@var{location} specifies source lines; there are several ways of
-writing them (@pxref{Specify Location}), but the effect is always to
-specify some source line.
+@item break @var{locspec} thread @var{thread-id}
+@itemx break @var{locspec} thread @var{thread-id} if @dots{}
+@var{locspec} specifies a code location or locations in your program.
+@xref{Location Specifications}, for details.
Use the qualifier @samp{thread @var{thread-id}} with a breakpoint command
to specify that you only want @value{GDBN} to stop the program when a
supports.
@smallexample
-(gdb) info record
+(@value{GDBP}) 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
+(@value{GDBP}) set record btrace cpu intel:6/158
+(@value{GDBP}) info record
Active record target: record-btrace
Recording format: Intel Processor Trace.
Buffer size: 16kB.
It can also print mixed source+disassembly if you specify the the
@code{/m} or @code{/s} modifier, and print the raw instructions in hex
-as well as in symbolic form by specifying the @code{/r} modifier.
+as well as in symbolic form by specifying the @code{/r} or @code{/b}
+modifier. The behaviour of the @code{/m}, @code{/s}, @code{/r}, and
+@code{/b} modifiers are the same as for the @kbd{disassemble} command
+(@pxref{disassemble,,@kbd{disassemble}}).
The current position marker is printed for the instruction at the
current program counter value. This instruction can appear multiple
@command{info frame}, for example:
@smallexample
-(gdb) info frame
+(@value{GDBP}) 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
@smallexample
@group
-(gdb) frame apply all p j
+(@value{GDBP}) 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
+(@value{GDBP}) 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
+(@value{GDBP}) frame apply all -s p j
#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11
$2 = 5
-(gdb)
+(@value{GDBP})
@end group
@end smallexample
@smallexample
@group
-(gdb) frame apply all p $sp
+(@value{GDBP}) 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)
+(@value{GDBP})
@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
+(@value{GDBP}) frame apply all -q p $sp
$12 = (void *) 0xffffd1e0
$13 = (void *) 0xffffd1f0
-(gdb)
+(@value{GDBP})
@end group
@end smallexample
Example:
@smallexample
-(gdb) info frame-filter
+(@value{GDBP}) info frame-filter
global frame-filters:
Priority Enabled Name
Priority Enabled Name
999 Yes BuildProgramFilter
-(gdb) disable frame-filter /build/test BuildProgramFilter
-(gdb) info frame-filter
+(@value{GDBP}) disable frame-filter /build/test BuildProgramFilter
+(@value{GDBP}) info frame-filter
global frame-filters:
Priority Enabled Name
Priority Enabled Name
999 No BuildProgramFilter
-(gdb) enable frame-filter global PrimaryFunctionFilter
-(gdb) info frame-filter
+(@value{GDBP}) enable frame-filter global PrimaryFunctionFilter
+(@value{GDBP}) info frame-filter
global frame-filters:
Priority Enabled Name
Example:
@smallexample
-(gdb) info frame-filter
+(@value{GDBP}) info frame-filter
global frame-filters:
Priority Enabled Name
Priority Enabled Name
999 No BuildProgramFilter
-(gdb) set frame-filter priority global Reverse 50
-(gdb) info frame-filter
+(@value{GDBP}) set frame-filter priority global Reverse 50
+(@value{GDBP}) info frame-filter
global frame-filters:
Priority Enabled Name
@menu
* List:: Printing source lines
-* Specify Location:: How to specify code locations
+* Location Specifications:: How to specify code locations
* Edit:: Editing source files
* Search:: Searching source files
* Source Path:: Specifying source directories
* Machine Code:: Source and machine code
-* Disable Reading Source:: Disable Reading Source Code
+* Disable Reading Source:: Disable Reading Source Code
@end menu
@node List
To print lines from a source file, use the @code{list} command
(abbreviated @code{l}). By default, ten lines are printed.
There are several ways to specify what part of the file you want to
-print; see @ref{Specify Location}, for the full list.
+print; see @ref{Location Specifications}, for the full list.
Here are the forms of the @code{list} command most commonly used:
argument of @samp{-}; that argument is preserved in repetition so that
each repetition moves up in the source file.
-In general, the @code{list} command expects you to supply zero, one or two
-@dfn{locations}. Locations specify source lines; there are several ways
-of writing them (@pxref{Specify Location}), but the effect is always
-to specify some source line.
+In general, the @code{list} command expects you to supply zero, one or
+two location specs. These location specs are interpreted to resolve
+to source code lines; there are several ways of writing them
+(@pxref{Location Specifications}), but the effect is always to resolve
+to some source lines to display.
Here is a complete description of the possible arguments for @code{list}:
@table @code
-@item list @var{location}
-Print lines centered around the line specified by @var{location}.
+@item list @var{locspec}
+Print lines centered around the line or lines of all the code
+locations that result from resolving @var{locspec}.
@item list @var{first},@var{last}
Print lines from @var{first} to @var{last}. Both arguments are
-locations. When a @code{list} command has two locations, and the
-source file of the second location is omitted, this refers to
-the same source file as the first location.
+location specs. When a @code{list} command has two location specs,
+and the source file of the second location spec is omitted, this
+refers to the same source file as the first location spec. If either
+@var{first} or @var{last} resolve to more than one source line in the
+program, then the list command shows the list of resolved source
+lines and does not proceed with the source code listing.
@item list ,@var{last}
Print lines ending with @var{last}.
+Likewise, if @var{last} resolves to more than one source line in the
+program, then the list command prints the list of resolved source
+lines and does not proceed with the source code listing.
+
@item list @var{first},
Print lines starting with @var{first}.
As described in the preceding table.
@end table
-@node Specify Location
-@section Specifying a Location
+@node Location Specifications
+@section Location Specifications
@cindex specifying location
-@cindex location
+@cindex locspec
@cindex source location
+@cindex code location
+@cindex location spec
Several @value{GDBN} commands accept arguments that specify a location
-of your program's code. Since @value{GDBN} is a source-level
-debugger, a location usually specifies some line in the source code.
-Locations may be specified using three different formats:
-linespec locations, explicit locations, or address locations.
+or locations of your program's code. Many times locations are
+specified using a source line number, but they can also be specified
+by a function name, an address, a label, etc. The different
+forms of specifying a location that @value{GDBN} recognizes are
+collectively known as forms of @dfn{location specification}, or
+@dfn{location spec}. This section documents the forms of specifying
+locations that @value{GDBN} recognizes.
+
+@cindex location resolution
+@cindex resolution of location spec
+When you specify a location, @value{GDBN} needs to find the place in
+your program, known as @dfn{code location}, that corresponds to the
+given location spec. We call this process of finding actual code
+locations corresponding to a location spec @dfn{location resolution}.
+
+A concrete code location in your program is uniquely identifiable by a
+set of several attributes: its source line number, the name of its
+source file, the fully-qualified and prototyped function in which it
+is defined, and an instruction address. Because each inferior has its
+own address space, the inferior number is also a necessary part of
+these attributes.
+
+By contrast, location specs you type will many times omit some of
+these attributes. For example, it is customary to specify just the
+source line number to mean a line in the current source file, or
+specify just the basename of the file, omitting its directories. In
+other words, a location spec is usually incomplete, a kind of
+blueprint, and @value{GDBN} needs to complete the missing attributes
+by using the implied defaults, and by considering the source code and
+the debug information available to it. This is what location
+resolution is about.
+
+The resolution of an incomplete location spec can produce more than a
+single code location, if the spec doesn't allow distinguishing between
+them. Here are some examples of situations that result in a location
+spec matching multiple code locations in your program:
+
+@itemize @bullet
+@item
+The location spec specifies a function name, and there are several
+functions in the program which have that name. (To distinguish
+between them, you can specify a fully-qualified and prototyped
+function name, such as @code{A::func(int)} instead of just
+@code{func}.)
+
+@item
+The location spec specifies a source file name, and there are several
+source files in the program that share the same name, for example
+several files with the same basename in different subdirectories. (To
+distinguish between them, specify enough leading directories with the
+file name.)
+
+@item
+For a C@t{++} constructor, the @value{NGCC} compiler generates several
+instances of the function body, used in different cases, but their
+source-level names are identical.
+
+@item
+For a C@t{++} template function, a given line in the function can
+correspond to any number of instantiations.
+
+@item
+For an inlined function, a given source line can correspond to several
+actual code locations with that function's inlined code.
+@end itemize
+
+Resolution of a location spec can also fail to produce a complete code
+location, or even fail to produce any code location. Here are some
+examples of such situations:
+
+@itemize @bullet
+@item
+Some parts of the program lack detailed enough debug info, so the
+resolved code location lacks some attributes, like source file name
+and line number, leaving just the instruction address and perhaps also
+a function name. Such an incomplete code location is only usable in
+contexts that work with addresses and/or function names. Some
+commands can only work with complete code locations.
+
+@item
+The location spec specifies a function name, and there are no
+functions in the program by that name, or they only exist in a
+yet-unloaded shared library.
+
+@item
+The location spec specifies a source file name, and there are no
+source files in the program by that name, or they only exist in a
+yet-unloaded shared library.
+
+@item
+The location spec specifies both a source file name and a source line
+number, and even though there are source files in the program that
+match the file name, none of those files has the specified line
+number.
+@end itemize
+
+Locations may be specified using three different formats: linespec
+locations, explicit locations, or address locations. The following
+subsections describe these formats.
@menu
* Linespec Locations:: Linespec locations
want to print if you want to see other parts of the program:
@table @code
-@item edit @var{location}
-Edit the source file specified by @code{location}. Editing starts at
-that @var{location}, e.g., at the specified source line of the
-specified file. @xref{Specify Location}, for all the possible forms
-of the @var{location} argument; here are the forms of the @code{edit}
-command most commonly used:
+@item edit @var{locspec}
+Edit the source file of the code location that results from resolving
+@code{locspec}. Editing starts at the source file and source line
+@code{locspec} resolves to.
+@xref{Location Specifications}, for all the possible forms of the
+@var{locspec} argument.
+
+If @code{locspec} resolves to more than one source line in your
+program, then the command prints the list of resolved source lines and
+does not proceed with the editing.
+
+Here are the forms of the @code{edit} command most commonly used:
@table @code
@item edit @var{number}
@table @code
@kindex info line
@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}. With no @var{location}
-information about the current source line is printed.
+@itemx info line @var{locspec}
+Print the starting and ending addresses of the compiled code for the
+source lines of the code locations that result from resolving
+@var{locspec}. @xref{Location Specifications}, for the various forms
+of @var{locspec}.
+With no @var{locspec}, information about the current source line is
+printed.
@end table
For example, we can use @code{info line} to discover the location of
@noindent
@cindex code address and its source line
-We can also inquire (using @code{*@var{addr}} as the form for
-@var{location}) what source line covers a particular address:
+We can also inquire, using @code{*@var{addr}} as the form for
+@var{locspec}, what source line covers a particular address
+@var{addr}:
@smallexample
(@value{GDBP}) info line *0x63ff
Line 926 of "builtin.c" starts at pc 0x63e4 <m4_changequote+152> and \
specifying a location will display information about the next source
line.
+@anchor{disassemble}
@table @code
@kindex disassemble
@cindex assembly instructions
@itemx disassemble /m
@itemx disassemble /s
@itemx disassemble /r
+@itemx disassemble /b
This specialized command dumps a range of memory as machine
instructions. It can also print mixed source+disassembly by specifying
-the @code{/m} or @code{/s} modifier and print the raw instructions in hex
-as well as in symbolic form by specifying the @code{/r} modifier.
-The default memory range is the function surrounding the
+the @code{/m} or @code{/s} modifier and print the raw instructions in
+hex as well as in symbolic form by specifying the @code{/r} or @code{/b}
+modifier. The default memory range is the function surrounding the
program counter of the selected frame. A single argument to this
command is a program counter value; @value{GDBN} dumps the function
-surrounding this value. When two arguments are given, they should
-be separated by a comma, possibly surrounded by whitespace. The
-arguments specify a range of addresses to dump, in one of two forms:
+surrounding this value. When two arguments are given, they should be
+separated by a comma, possibly surrounded by whitespace. The arguments
+specify a range of addresses to dump, in one of two forms:
@table @code
@item @var{start},@var{end}
End of assembler dump.
@end smallexample
+The following two examples are for RISC-V, and demonstrates the
+difference between the @code{/r} and @code{/b} modifiers. First with
+@code{/b}, the bytes of the instruction are printed, in hex, in memory
+order:
+
+@smallexample
+(@value{GDBP}) disassemble /b 0x00010150,0x0001015c
+Dump of assembler code from 0x10150 to 0x1015c:
+ 0x00010150 <call_me+4>: 22 dc sw s0,56(sp)
+ 0x00010152 <call_me+6>: 80 00 addi s0,sp,64
+ 0x00010154 <call_me+8>: 23 26 a4 fe sw a0,-20(s0)
+ 0x00010158 <call_me+12>: 23 24 b4 fe sw a1,-24(s0)
+End of assembler dump.
+@end smallexample
+
+In contrast, with @code{/r} the bytes of the instruction are displayed
+in the instruction order, for RISC-V this means that the bytes have been
+swapped to little-endian order:
+
+@smallexample
+(@value{GDBP}) disassemble /r 0x00010150,0x0001015c
+Dump of assembler code from 0x10150 to 0x1015c:
+ 0x00010150 <call_me+4>: dc22 sw s0,56(sp)
+ 0x00010152 <call_me+6>: 0080 addi s0,sp,64
+ 0x00010154 <call_me+8>: fea42623 sw a0,-20(s0)
+ 0x00010158 <call_me+12>: feb42423 sw a1,-24(s0)
+End of assembler dump.
+@end smallexample
+
Here is an example showing mixed source+assembly for Intel x86
with @code{/m} or @code{/s}, when the program is stopped just after
function prologue in a non-optimized function with no inline code.
Here is another example showing raw instructions in hex for AMD x86-64,
@smallexample
-(gdb) disas /r 0x400281,+10
+(@value{GDBP}) disas /r 0x400281,+10
Dump of assembler code from 0x400281 to 0x40028b:
0x0000000000400281: 38 36 cmp %dh,(%rsi)
0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax
End of assembler dump.
@end smallexample
-Addresses cannot be specified as a location (@pxref{Specify Location}).
-So, for example, if you want to disassemble function @code{bar}
-in file @file{foo.c}, you must type @samp{disassemble 'foo.c'::bar}
-and not @samp{disassemble foo.c:bar}.
+Note that the @samp{disassemble} command's address arguments are
+specified using expressions in your programming language
+(@pxref{Expressions, ,Expressions}), not location specs
+(@pxref{Location Specifications}). So, for example, if you want to
+disassemble function @code{bar} in file @file{foo.c}, you must type
+@samp{disassemble 'foo.c'::bar} and not @samp{disassemble foo.c:bar}.
Some architectures have more than one commonly-used set of instruction
mnemonics or other syntax.
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
+@item -characters @var{number-of-characters}|@code{elements}|@code{unlimited}
+Set limit on string characters to print. The value @code{elements}
+causes the limit on array elements to print to be used. The value
@code{unlimited} causes there to be no limit. Related setting:
-@ref{set print elements}.
+@ref{set print characters}.
+
+@item -elements @var{number-of-elements}|@code{unlimited}
+Set limit on array elements and optionally string characters to print.
+See @ref{set print characters}, and the @code{-characters} option above
+for when this option applies to strings. The value @code{unlimited}
+causes there to be no limit. @xref{set print elements}, for a related
+CLI command.
@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 -nibbles [@code{on}|@code{off}]
+Set whether to print binary values in groups of four bits, known
+as ``nibbles''. @xref{set print nibbles}.
+
@item -memory-tag-violations [@code{on}|@code{off}]
Set printing of additional information about memory tag violations.
@xref{set print memory-tag-violations}.
specified format. @xref{Memory, ,Examining Memory}.
If you are interested in information about types, or about how the
-fields of a struct or a class are declared, use the @code{ptype @var{exp}}
+fields of a struct or a class are declared, use the @code{ptype @var{expr}}
command rather than @code{print}. @xref{Symbols, ,Examining the Symbol
Table}.
@code{explore} command as follows.
@smallexample
-(gdb) explore cs
+(@value{GDBP}) explore cs
The value of `cs' is a struct/class of type `struct ComplexStruct' with
the following fields:
@code{struct ComplexStruct} to the @code{explore} command.
@smallexample
-(gdb) explore struct ComplexStruct
+(@value{GDBP}) explore struct ComplexStruct
@end smallexample
@noindent
@smallexample
Breakpoint 1, d (i=30) at gdb.base/entry-value.c:29
29 i++;
-(gdb) next
+(@value{GDBP}) next
30 e (i);
-(gdb) print i
+(@value{GDBP}) print i
$1 = 31
-(gdb) print i@@entry
+(@value{GDBP}) print i@@entry
$2 = 30
@end smallexample
You get during debugging
@smallexample
-(gdb) print var0
+(@value{GDBP}) print var0
$1 = "A"
-(gdb) print var1
+(@value{GDBP}) print var1
$2 = @{65 'A', 0 '\0'@}
@end smallexample
@table @code
@item x
-Regard the bits of the value as an integer, and print the integer in
-hexadecimal.
+Print the binary representation of the value in hexadecimal.
@item d
-Print as integer in signed decimal.
+Print the binary representation of the value in decimal.
@item u
-Print as integer in unsigned decimal.
+Print the binary representation of the value as an decimal, as if it
+were unsigned.
@item o
-Print as integer in octal.
+Print the binary representation of the value in octal.
@item t
-Print as integer in binary. The letter @samp{t} stands for ``two''.
-@footnote{@samp{b} cannot be used because these format letters are also
-used with the @code{x} command, where @samp{b} stands for ``byte'';
-see @ref{Memory,,Examining Memory}.}
+Print the binary representation of the value in binary. The letter
+@samp{t} stands for ``two''. @footnote{@samp{b} cannot be used
+because these format letters are also used with the @code{x} command,
+where @samp{b} stands for ``byte''; see @ref{Memory,,Examining
+Memory}.}
@item a
@cindex unknown address, locating
@xref{Symbols, info symbol}.
@item c
-Regard as an integer and print it as a character constant. This
-prints both the numerical value and its character representation. The
-character representation is replaced with the octal escape @samp{\nnn}
-for characters outside the 7-bit @sc{ascii} range.
+Cast the value to an integer (unlike other formats, this does not just
+reinterpret the underlying bits) and print it as a character constant.
+This prints both the numerical value and its character representation.
+The character representation is replaced with the octal escape
+@samp{\nnn} for characters outside the 7-bit @sc{ascii} range.
Without this format, @value{GDBN} displays @code{char},
@w{@code{unsigned char}}, and @w{@code{signed char}} data as character
Show whether the index of each element is printed when displaying
arrays.
+@anchor{set print nibbles}
+@item set print nibbles
+@itemx set print nibbles on
+@cindex print binary values in groups of four bits
+Print binary values in groups of four bits, known as @dfn{nibbles},
+when using the print command of @value{GDBN} with the option @samp{/t}.
+For example, this is what it looks like with @code{set print nibbles on}:
+
+@smallexample
+@group
+(@value{GDBP}) print val_flags
+$1 = 1230
+(@value{GDBP}) print/t val_flags
+$2 = 0100 1100 1110
+@end group
+@end smallexample
+
+@item set print nibbles off
+Don't printing binary values in groups. This is the default.
+
+@item show print nibbles
+Show whether to print binary values in groups of four bits.
+
+@anchor{set print characters}
+@item set print characters @var{number-of-characters}
+@itemx set print characters elements
+@itemx set print characters unlimited
+@cindex number of string characters to print
+@cindex limit on number of printed string characters
+Set a limit on how many characters of a string @value{GDBN} will print.
+If @value{GDBN} is printing a large string, it stops printing after it
+has printed the number of characters set by the @code{set print
+characters} command. This equally applies to multi-byte and wide
+character strings, that is for strings whose character type is
+@code{wchar_t}, @code{char16_t}, or @code{char32_t} it is the number of
+actual characters rather than underlying bytes the encoding uses that
+this setting controls.
+Setting @var{number-of-characters} to @code{elements} means that the
+limit on the number of characters to print follows one for array
+elements; see @ref{set print elements}.
+Setting @var{number-of-characters} to @code{unlimited} means that the
+number of characters to print is unlimited.
+When @value{GDBN} starts, this limit is set to @code{elements}.
+
+@item show print characters
+Display the number of characters of a large string that @value{GDBN}
+will print.
+
@anchor{set print elements}
@item set print elements @var{number-of-elements}
@itemx set print elements unlimited
Set a limit on how many elements of an array @value{GDBN} will print.
If @value{GDBN} is printing a large array, it stops printing after it has
printed the number of elements set by the @code{set print elements} command.
-This limit also applies to the display of strings.
+By default this limit also applies to the display of strings; see
+@ref{set print characters}.
When @value{GDBN} starts, this limit is set to 200.
Setting @var{number-of-elements} to @code{unlimited} or zero means
that the number of elements to print is unlimited.
+When printing very large arrays, whose size is greater than
+@code{max-value-size} (@pxref{set max-value-size,,max-value-size}),
+if the @code{print elements} is set such that the size of the elements
+being printed is less than or equal to @code{max-value-size}, then
+@value{GDBN} will print the array (up to the @code{print elements} limit),
+and only @code{max-value-size} worth of data will be added into the value
+history (@pxref{Value History, ,Value History}).
+
@item show print elements
Display the number of elements of a large array that @value{GDBN} will print.
the structure that are visible, for example
@smallexample
-(gdb) set print max-depth 2
-(gdb) p var
+(@value{GDBP}) set print max-depth 2
+(@value{GDBP}) p var
$1 = @{d = @{c = @{...@}@}@}
-(gdb) p var.d
+(@value{GDBP}) p var.d
$2 = @{c = @{b = @{...@}@}@}
-(gdb) p var.d.c
+(@value{GDBP}) p var.d.c
$3 = @{b = @{a = 3@}@}
@end smallexample
@code{bar1} and @code{bar2}.
@smallexample
-(gdb) info pretty-printer
+@group
+(@value{GDBP}) info pretty-printer
library1.so:
foo
library2.so:
bar
bar1
bar2
-(gdb) info pretty-printer library2
+@end group
+@group
+(@value{GDBP}) info pretty-printer library2
library2.so:
bar
bar1
bar2
-(gdb) disable pretty-printer library1
+@end group
+@group
+(@value{GDBP}) disable pretty-printer library1
1 printer disabled
2 of 3 printers enabled
-(gdb) info pretty-printer
+(@value{GDBP}) info pretty-printer
library1.so:
foo [disabled]
library2.so:
bar
bar1
bar2
-(gdb) disable pretty-printer library2 bar;bar1
+@end group
+@group
+(@value{GDBP}) disable pretty-printer library2 bar;bar1
1 printer disabled
1 of 3 printers enabled
-(gdb) info pretty-printer library2
-library1.so:
- foo [disabled]
+(@value{GDBP}) info pretty-printer library2
library2.so:
bar
bar1 [disabled]
bar2
-(gdb) disable pretty-printer library2 bar
+@end group
+@group
+(@value{GDBP}) disable pretty-printer library2 bar
1 printer disabled
0 of 3 printers enabled
-(gdb) info pretty-printer library2
+(@value{GDBP}) info pretty-printer
library1.so:
foo [disabled]
library2.so:
bar [disabled]
bar1 [disabled]
bar2
+@end group
@end smallexample
Note that for @code{bar} the entire printer can be disabled,
@item $_gthread
The global number of the current thread. @xref{global thread numbers}.
+@item $_inferior_thread_count
+The number of live threads in the current inferior. @xref{Threads}.
+
@item $_gdb_major
@itemx $_gdb_minor
@vindex $_gdb_major@r{, convenience variable}
@table @code
-@item $_isvoid (@var{expr})
@findex $_isvoid@r{, convenience function}
+@item $_isvoid (@var{expr})
Return one if the expression @var{expr} is @code{void}. Otherwise it
returns zero.
$4 = 1
@end smallexample
-@item $_gdb_setting_str (@var{setting})
@findex $_gdb_setting_str@r{, convenience function}
+@item $_gdb_setting_str (@var{setting})
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}).
(@value{GDBP})
@end smallexample
-@item $_gdb_setting (@var{setting})
@findex $_gdb_setting@r{, convenience function}
+@item $_gdb_setting (@var{setting})
Return the value of the @value{GDBN} @var{setting}.
The type of the returned value depends on the setting.
are returned as string values.
-@item $_gdb_maint_setting_str (@var{setting})
@findex $_gdb_maint_setting_str@r{, convenience function}
+@item $_gdb_maint_setting_str (@var{setting})
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}
+@item $_gdb_maint_setting (@var{setting})
Like the @code{$_gdb_setting} function, but works with
@code{maintenance set} variables.
+@anchor{$_shell convenience function}
+@findex $_shell@r{, convenience function}
+@item $_shell (@var{command-string})
+
+Invoke a shell to execute @var{command-string}. @var{command-string}
+must be a string. The shell runs on the host machine, the machine
+@value{GDBN} is running on. Returns the command's exit status. On
+Unix systems, a command which exits with a zero exit status has
+succeeded, and non-zero exit status indicates failure. When a command
+terminates on a fatal signal whose number is @var{N}, @value{GDBN}
+uses the value 128+@var{N} as the exit status, as is standard in Unix
+shells. Note that @var{N} is a host signal number, not a target
+signal number. If you're native debugging, they will be the same, but
+if cross debugging, the host vs target signal numbers may be
+completely unrelated. Please consult your host operating system's
+documentation for the mapping between host signal numbers and signal
+names. The shell to run is determined in the same way as for the
+@code{shell} command. @xref{Shell Commands, ,Shell Commands}.
+
+@smallexample
+(@value{GDBP}) print $_shell("true")
+$1 = 0
+(@value{GDBP}) print $_shell("false")
+$2 = 1
+(@value{GDBP}) p $_shell("echo hello")
+hello
+$3 = 0
+(@value{GDBP}) p $_shell("foobar")
+bash: line 1: foobar: command not found
+$4 = 127
+@end smallexample
+
+This may also be useful in breakpoint conditions. For example:
+
+@smallexample
+(@value{GDBP}) break function if $_shell("some command") == 0
+@end smallexample
+
+In this scenario, you'll want to make sure that the shell command you
+run in the breakpoint condition takes the least amount of time
+possible. For example, avoid running a command that may block
+indefinitely, or that sleeps for a while before exiting. Prefer a
+command or script which analyzes some state and exits immediately.
+This is important because the debugged program stops for the
+breakpoint every time, and then @value{GDBN} evaluates the breakpoint
+condition. If the condition is false, the program is re-resumed
+transparently, without informing you of the stop. A quick shell
+command thus avoids significantly slowing down the debugged program
+unnecessarily.
+
+Note: unlike the @code{shell} command, the @code{$_shell} convenience
+function does not affect the @code{$_shell_exitcode} and
+@code{$_shell_exitsignal} convenience variables.
+
@end table
The following functions require @value{GDBN} to be configured with
@table @code
-@item $_memeq(@var{buf1}, @var{buf2}, @var{length})
@findex $_memeq@r{, convenience function}
+@item $_memeq(@var{buf1}, @var{buf2}, @var{length})
Returns one if the @var{length} bytes at the addresses given by
@var{buf1} and @var{buf2} are equal.
Otherwise it returns zero.
-@item $_regex(@var{str}, @var{regex})
@findex $_regex@r{, convenience function}
+@item $_regex(@var{str}, @var{regex})
Returns one if the string @var{str} matches the regular expression
@var{regex}. Otherwise it returns zero.
The syntax of the regular expression is that specified by @code{Python}'s
regular expression support.
-@item $_streq(@var{str1}, @var{str2})
@findex $_streq@r{, convenience function}
+@item $_streq(@var{str1}, @var{str2})
Returns one if the strings @var{str1} and @var{str2} are equal.
Otherwise it returns zero.
-@item $_strlen(@var{str})
@findex $_strlen@r{, convenience function}
+@item $_strlen(@var{str})
Returns the length of string @var{str}.
-@item $_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]})
@findex $_caller_is@r{, convenience function}
+@item $_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]})
Returns one if the calling function's name is equal to @var{name}.
Otherwise it returns zero.
Example:
@smallexample
-(gdb) backtrace
+(@value{GDBP}) backtrace
#0 bottom_func ()
at testsuite/gdb.python/py-caller-is.c:21
#1 0x00000000004005a0 in middle_func ()
at testsuite/gdb.python/py-caller-is.c:33
#3 0x00000000004005b6 in main ()
at testsuite/gdb.python/py-caller-is.c:39
-(gdb) print $_caller_is ("middle_func")
+(@value{GDBP}) print $_caller_is ("middle_func")
$1 = 1
-(gdb) print $_caller_is ("top_func", 2)
+(@value{GDBP}) print $_caller_is ("top_func", 2)
$1 = 1
@end smallexample
-@item $_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]})
@findex $_caller_matches@r{, convenience function}
+@item $_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]})
Returns one if the calling function's name matches the regular expression
@var{regexp}. Otherwise it returns zero.
it is the number of frames up in the stack to look.
The default is 1.
-@item $_any_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]})
@findex $_any_caller_is@r{, convenience function}
+@item $_any_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]})
Returns one if any calling function's name is equal to @var{name}.
Otherwise it returns zero.
by @var{number_of_frames}, whereas @code{$_caller_is} only checks the
frame specified by @var{number_of_frames}.
-@item $_any_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]})
@findex $_any_caller_matches@r{, convenience function}
+@item $_any_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]})
Returns one if any calling function's name matches the regular expression
@var{regexp}. Otherwise it returns zero.
by @var{number_of_frames}, whereas @code{$_caller_matches} only checks the
frame specified by @var{number_of_frames}.
-@item $_as_string(@var{value})
@findex $_as_string@r{, convenience function}
+@item $_as_string(@var{value})
Return the string representation of @var{value}.
This function is useful to obtain the textual label (enumerator) of an
an enumerated type:
@smallexample
-(gdb) printf "Visiting node of type %s\n", $_as_string(node)
+(@value{GDBP}) printf "Visiting node of type %s\n", $_as_string(node)
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}
+@item $_cimag(@var{value})
+@itemx $_creal(@var{value})
Return the imaginary (@code{$_cimag}) or real (@code{$_creal}) part of
the complex number @var{value}.
you get during debugging:
@smallexample
-(gdb) find &hello[0], +sizeof(hello), "hello"
+(@value{GDBP}) find &hello[0], +sizeof(hello), "hello"
0x804956d <hello.1620+6>
1 pattern found
-(gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o'
+(@value{GDBP}) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o'
0x8049567 <hello.1620>
0x804956d <hello.1620+6>
2 patterns found.
-(gdb) find &hello[0], +sizeof(hello), @{char[5]@}"hello"
+(@value{GDBP}) 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'
+(@value{GDBP}) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l'
0x8049567 <hello.1620>
1 pattern found
-(gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321
+(@value{GDBP}) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321
0x8049560 <mixed.1625>
1 pattern found
-(gdb) print $numfound
+(@value{GDBP}) print $numfound
$1 = 1
-(gdb) print $_
+(@value{GDBP}) print $_
$2 = (void *) 0x8049560
@end smallexample
@value{GDBN} to try and allocate an overly large amount of memory.
@table @code
+@anchor{set max-value-size}
@kindex set max-value-size
@item set max-value-size @var{bytes}
@itemx set max-value-size unlimited
kind by text @code{tail call frame} such as in this sample @value{GDBN} output:
@smallexample
-(gdb) x/i $pc - 2
+(@value{GDBP}) x/i $pc - 2
0x40066b <b(int, double)+11>: jmp 0x400640 <c(int, double)>
-(gdb) info frame
+(@value{GDBP}) 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
DW_TAG_call_site 0x40039a in main
a () at t.c:3
3 static void __attribute__((noinline, noclone)) a (void) @{ x++; @}
-(gdb) bt
+(@value{GDBP}) bt
#0 a () at t.c:3
#1 0x000000000040039a in main () at t.c:5
@end smallexample
tailcall: initial: 0x4004d2(a) 0x4004ce(b) 0x4004b2(c) 0x4004a2(d)
tailcall: compare: 0x4004d2(a) 0x4004cc(b) 0x400492(e)
tailcall: reduced: 0x4004d2(a) |
-(gdb) bt
+(@value{GDBP}) bt
#0 f () at t.c:2
#1 0x00000000004004d2 in a () at t.c:8
#2 0x0000000000400395 in main () at t.c:9
@{ if (i) b (i - 1); else c (0); @}
int main (void) @{ a (5); return 0; @}
-(gdb) bt
+(@value{GDBP}) bt
#0 c (i=i@@entry=0) at t.c:2
#1 0x0000000000400428 in a (DW_OP_entry_value resolving has found
function "a" at 0x400420 can call itself via tail calls
the macro may begin with a hyphen.
@kindex info macros
-@item info macros @var{location}
-Show all macro definitions that are in effect at the location specified
-by @var{location}, and describe the source location or compiler
-command-line where those definitions were established.
+@item info macros @var{locspec}
+Show all macro definitions that are in effect at the source line of
+the code location that results from resolving @var{locspec}, and
+describe the source location or compiler command-line where those
+definitions were established.
@kindex macro define
@cindex user-defined macros
@table @code
@cindex set tracepoint
@kindex trace
-@item trace @var{location}
+@item trace @var{locspec}
The @code{trace} command is very similar to the @code{break} command.
-Its argument @var{location} can be any valid location.
-@xref{Specify Location}. The @code{trace} command defines a tracepoint,
+Its argument @var{locspec} can be any valid location specification.
+@xref{Location Specifications}. The @code{trace} command defines a tracepoint,
which is a point in the target program where the debugger will briefly stop,
collect some data, and then allow the program to continue. Setting a tracepoint
or changing its actions takes effect immediately if the remote stub
@noindent
You can abbreviate @code{trace} as @code{tr}.
-@item trace @var{location} if @var{cond}
+@item trace @var{locspec} if @var{cond}
Set a tracepoint with condition @var{cond}; evaluate the expression
@var{cond} each time the tracepoint is reached, and collect data only
if the value is nonzero---that is, if @var{cond} evaluates as true.
@xref{Tracepoint Conditions, ,Tracepoint Conditions}, for more
information on tracepoint conditions.
-@item ftrace @var{location} [ if @var{cond} ]
+@item ftrace @var{locspec} [ if @var{cond} ]
@cindex set fast tracepoint
@cindex fast tracepoints, setting
@kindex ftrace
which sets the low address to 32K, which leaves plenty of room for
trampolines. The minimum address should be set to a page boundary.
-@item strace @var{location} [ if @var{cond} ]
+@item strace [@var{locspec} | -m @var{marker}] [ if @var{cond} ]
@cindex set static tracepoint
@cindex static tracepoints, setting
@cindex probe static tracepoint marker
@kindex strace
The @code{strace} command sets a static tracepoint. For targets that
support it, setting a static tracepoint probes a static
-instrumentation point, or marker, found at @var{location}. It may not
-be possible to set a static tracepoint at the desired location, in
-which case the command will exit with an explanatory message.
+instrumentation point, or marker, found at the code locations that
+result from resolving @var{locspec}. It may not be possible to set a
+static tracepoint at the desired code location, in which case the
+command will exit with an explanatory message.
@value{GDBN} handles arguments to @code{strace} exactly as for
@code{trace}, with the addition that the user can also specify
-@code{-m @var{marker}} as @var{location}. This probes the marker
+@code{-m @var{marker}} instead of a location spec. This probes the marker
identified by the @var{marker} string identifier. This identifier
depends on the static tracepoint backend library your program is
using. You can find all the marker identifiers in the @samp{ID} field
@code{s} requests that pointers to chars be handled as strings, in
particular collecting the contents of the memory being pointed at, up
to the first zero. The upper bound is by default the value of the
-@code{print elements} variable; if @code{s} is followed by a decimal
+@code{print characters} variable; if @code{s} is followed by a decimal
number, that is the upper bound instead. So for instance
@samp{collect/s25 mystr} collects as many as 25 characters at
@samp{mystr}.
tag. For example:
@smallexample
-(gdb) b function(int)
+(@value{GDBP}) b function(int)
Breakpoint 2 at 0x40060d: file main.cc, line 10.
-(gdb) info breakpoints
+(@value{GDBP}) info breakpoints
Num Type Disp Enb Address What
1 breakpoint keep y 0x0040060d in function[abi:cxx11](int)
at main.cc:10
When stopped inside @code{main} either of these work:
@example
-(gdb) p myglob
-(gdb) p main.myglob
+(@value{GDBP}) p myglob
+(@value{GDBP}) p main.myglob
@end example
@cindex builtin Go types
@subsection Fortran
@cindex Fortran-specific support in @value{GDBN}
-@value{GDBN} can be used to debug programs written in Fortran, but it
-currently supports only the features of Fortran 77 language.
+@value{GDBN} can be used to debug programs written in Fortran. Note, that not
+all Fortran language features are available yet.
@cindex trailing underscore, in Fortran symbols
Some Fortran compilers (@sc{gnu} Fortran 77 and Fortran 95 compilers
will need to refer to variables and functions with a trailing
underscore.
+@cindex Fortran Defaults
+Fortran symbols are usually case-insensitive, so @value{GDBN} by
+default uses case-insensitive matching for Fortran symbols. You can
+change that with the @samp{set case-insensitive} command, see
+@ref{Symbols}, for the details.
+
@menu
+* Fortran Types:: Fortran builtin types
* Fortran Operators:: Fortran operators and expressions
-* Fortran Defaults:: Default settings for Fortran
+* Fortran Intrinsics:: Fortran intrinsic functions
* Special Fortran Commands:: Special @value{GDBN} commands for Fortran
@end menu
+@node Fortran Types
+@subsubsection Fortran Types
+
+@cindex Fortran Types
+
+In Fortran the primitive data-types have an associated @code{KIND} type
+parameter, written as @samp{@var{type}*@var{kindparam}},
+@samp{@var{type}*@var{kindparam}}, or in the @value{GDBN}-only dialect
+@samp{@var{type}_@var{kindparam}}. A concrete example would be
+@samp{@code{Real*4}}, @samp{@code{Real(kind=4)}}, and @samp{@code{Real_4}}.
+The kind of a type can be retrieved by using the intrinsic function
+@code{KIND}, see @ref{Fortran Intrinsics}.
+
+Generally, the actual implementation of the @code{KIND} type parameter is
+compiler specific. In @value{GDBN} the kind parameter is implemented in
+accordance with its use in the @sc{gnu} @command{gfortran} compiler. Here, the
+kind parameter for a given @var{type} specifies its size in memory --- a
+Fortran @code{Integer*4} or @code{Integer(kind=4)} would be an integer type
+occupying 4 bytes of memory. An exception to this rule is the @code{Complex}
+type for which the kind of the type does not specify its entire size, but
+the size of each of the two @code{Real}'s it is composed of. A
+@code{Complex*4} would thus consist of two @code{Real*4}s and occupy 8 bytes
+of memory.
+
+For every type there is also a default kind associated with it, e.g.@
+@code{Integer} in @value{GDBN} will internally be an @code{Integer*4} (see the
+table below for default types). The default types are the same as in @sc{gnu}
+compilers but note, that the @sc{gnu} default types can actually be changed by
+compiler flags such as @option{-fdefault-integer-8} and
+@option{-fdefault-real-8}.
+
+Not every kind parameter is valid for every type and in @value{GDBN} the
+following type kinds are available.
+
+@table @code
+@item Integer
+@code{Integer*1}, @code{Integer*2}, @code{Integer*4}, @code{Integer*8}, and
+@code{Integer} = @code{Integer*4}.
+
+@item Logical
+@code{Logical*1}, @code{Logical*2}, @code{Logical*4}, @code{Logical*8}, and
+@code{Logical} = @code{Logical*4}.
+
+@item Real
+@code{Real*4}, @code{Real*8}, @code{Real*16}, and @code{Real} = @code{Real*4}.
+
+@item Complex
+@code{Complex*4}, @code{Complex*8}, @code{Complex*16}, and @code{Complex} =
+@code{Complex*4}.
+
+@end table
+
@node Fortran Operators
@subsubsection Fortran Operators and Expressions
subroutines (internal subroutines).
@end table
-@node Fortran Defaults
-@subsubsection Fortran Defaults
+@node Fortran Intrinsics
+@subsubsection Fortran Intrinsics
-@cindex Fortran Defaults
+@cindex Fortran Intrinsics
-Fortran symbols are usually case-insensitive, so @value{GDBN} by
-default uses case-insensitive matches for Fortran symbols. You can
-change that with the @samp{set case-insensitive} command, see
-@ref{Symbols}, for the details.
+Fortran provides a large set of intrinsic procedures. @value{GDBN} implements
+an incomplete subset of those procedures and their overloads. Some of these
+procedures take an optional @code{KIND} parameter, see @ref{Fortran Types}.
+
+@table @code
+@item ABS(@var{a})
+Computes the absolute value of its argument @var{a}. Currently not supported
+for @code{Complex} arguments.
+
+@item ALLOCATE(@var{array})
+Returns whether @var{array} is allocated or not.
+
+@item ASSOCIATED(@var{pointer} [, @var{target}])
+Returns the association status of the pointer @var{pointer} or, if @var{target}
+is present, whether @var{pointer} is associated with the target @var{target}.
+
+@item CEILING(@var{a} [, @var{kind}])
+Computes the least integer greater than or equal to @var{a}. The optional
+parameter @var{kind} specifies the kind of the return type
+@code{Integer(@var{kind})}.
+
+@item CMPLX(@var{x} [, @var{y} [, @var{kind}]])
+Returns a complex number where @var{x} is converted to the real component. If
+@var{y} is present it is converted to the imaginary component. If @var{y} is
+not present then the imaginary component is set to @code{0.0} except if @var{x}
+itself is of @code{Complex} type. The optional parameter @var{kind} specifies
+the kind of the return type @code{Complex(@var{kind})}.
+
+@item FLOOR(@var{a} [, @var{kind}])
+Computes the greatest integer less than or equal to @var{a}. The optional
+parameter @var{kind} specifies the kind of the return type
+@code{Integer(@var{kind})}.
+
+@item KIND(@var{a})
+Returns the kind value of the argument @var{a}, see @ref{Fortran Types}.
+
+@item LBOUND(@var{array} [, @var{dim} [, @var{kind}]])
+Returns the lower bounds of an @var{array}, or a single lower bound along the
+@var{dim} dimension if present. The optional parameter @var{kind} specifies
+the kind of the return type @code{Integer(@var{kind})}.
+
+@item LOC(@var{x})
+Returns the address of @var{x} as an @code{Integer}.
+
+@item MOD(@var{a}, @var{p})
+Computes the remainder of the division of @var{a} by @var{p}.
+
+@item MODULO(@var{a}, @var{p})
+Computes the @var{a} modulo @var{p}.
+
+@item RANK(@var{a})
+Returns the rank of a scalar or array (scalars have rank @code{0}).
+
+@item SHAPE(@var{a})
+Returns the shape of a scalar or array (scalars have shape @samp{()}).
+
+@item SIZE(@var{array}[, @var{dim} [, @var{kind}]])
+Returns the extent of @var{array} along a specified dimension @var{dim}, or the
+total number of elements in @var{array} if @var{dim} is absent. The optional
+parameter @var{kind} specifies the kind of the return type
+@code{Integer(@var{kind})}.
+
+@item UBOUND(@var{array} [, @var{dim} [, @var{kind}]])
+Returns the upper bounds of an @var{array}, or a single upper bound along the
+@var{dim} dimension if present. The optional parameter @var{kind} specifies
+the kind of the return type @code{Integer(@var{kind})}.
+
+@end table
@node Special Fortran Commands
@subsubsection Special Fortran Commands
@itemize @bullet
@item
-Linespecs (@pxref{Specify Location}) are never relative to the current
-crate. Instead, they act as if there were a global namespace of
-crates, somewhat similar to the way @code{extern crate} behaves.
+Linespecs (@pxref{Location Specifications}) are never relative to the
+current crate. Instead, they act as if there were a global namespace
+of crates, somewhat similar to the way @code{extern crate} behaves.
That is, if @value{GDBN} is stopped at a breakpoint in a function in
crate @samp{A}, module @samp{B}, then @code{break B::f} will attempt
* 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 Source Character Set:: Character set of Ada source files.
* Ada Glitches:: Known peculiarities of Ada mode.
@end menu
@end itemize
@item
-The names in
-@code{Characters.Latin_1} are not available and
-concatenation is not implemented. Thus, escape characters in strings are
-not currently available.
+The names in @code{Characters.Latin_1} are not available.
@item
Equality tests (@samp{=} and @samp{/=}) on arrays test for bitwise
@item Child Activation Wait
The task is waiting for created tasks to complete activation.
-@item Accept Statement
+@item Accept or Select Term
The task is waiting on an accept or selective wait statement.
@item Waiting on entry call
The task is sleeping waiting for tasks on terminate alternatives to
finish terminating.
+@item Asynchronous Hold
+The task has been held by @code{Ada.Asynchronous_Task_Control.Hold_Task}.
+
+@item Activating
+The task has been created and is being made runnable.
+
+@item Selective Wait
+The task is waiting in a selective wait statement.
+
@item Accepting RV with @var{taskno}
The task is accepting a rendez-vous with the task @var{taskno}.
+
+@item Waiting on RV with @var{taskno}
+The task is waiting for a rendez-vous with the task @var{taskno}.
@end table
@item Name
Flags @code{-c} and @code{-s} cannot be used together.
-@item break @var{location} task @var{taskno}
-@itemx break @var{location} task @var{taskno} if @dots{}
+@item break @var{locspec} task @var{taskno}
+@itemx break @var{locspec} task @var{taskno} if @dots{}
@cindex breakpoints and tasks, in Ada
@cindex task breakpoints, in Ada
@kindex break @dots{} task @var{taskno}@r{ (Ada)}
These commands are like the @code{break @dots{} thread @dots{}}
-command (@pxref{Thread Stops}). The
-@var{location} argument specifies source lines, as described
-in @ref{Specify Location}.
+command (@pxref{Thread Stops}). @xref{Location Specifications}, for
+the various forms of @var{locspec}.
Use the qualifier @samp{task @var{taskno}} with a breakpoint command
to specify that you only want @value{GDBN} to stop the program when a
initialization sequence. If you need to debug this code, you should
use @code{set ravenscar task-switching off}.
-@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 Source Character Set
@subsubsection Ada Source Character Set
@cindex Ada, source character set
@kindex info scope
@cindex local variables
-@item info scope @var{location}
-List all the variables local to a particular scope. This command
-accepts a @var{location} argument---a function name, a source line, or
-an address preceded by a @samp{*}, and prints all the variables local
-to the scope defined by that location. (@xref{Specify Location}, for
-details about supported forms of @var{location}.) For example:
+@item info scope @var{locspec}
+List all the variables local to the lexical scope of the code location
+that results from resolving @var{locspec}. @xref{Location
+Specifications}, for details about supported forms of @var{locspec}.
+For example:
@smallexample
(@value{GDBP}) @b{info scope command_line_handler}
List the @code{struct linetable} from all @code{struct symtab}
instances whose name matches @var{regexp}. If @var{regexp} is not
given, list the @code{struct linetable} from all @code{struct symtab}.
+For example:
+
+@smallexample
+(@value{GDBP}) maint info line-table
+objfile: /home/gnu/build/a.out ((struct objfile *) 0x6120000e0d40)
+compunit_symtab: simple.cpp ((struct compunit_symtab *) 0x6210000ff450)
+symtab: /home/gnu/src/simple.cpp ((struct symtab *) 0x6210000ff4d0)
+linetable: ((struct linetable *) 0x62100012b760):
+INDEX LINE ADDRESS IS-STMT PROLOGUE-END
+0 3 0x0000000000401110 Y
+1 4 0x0000000000401114 Y Y
+2 9 0x0000000000401120 Y
+3 10 0x0000000000401124 Y Y
+4 10 0x0000000000401129
+5 15 0x0000000000401130 Y
+6 16 0x0000000000401134 Y Y
+7 16 0x0000000000401139
+8 21 0x0000000000401140 Y
+9 22 0x000000000040114f Y Y
+10 22 0x0000000000401154
+11 END 0x000000000040115a Y
+@end smallexample
+@noindent
+The @samp{IS-STMT} column indicates if the address is a recommended breakpoint
+location to represent a line or a statement. The @samp{PROLOGUE-END} column
+indicates that a given address is an adequate place to set a breakpoint at the
+first instruction following a function prologue.
@kindex maint set symbol-cache-size
@cindex symbol cache size
flush-symbol-cache} is deprecated in favor of @code{maint flush
symbol-cache}..
+@kindex maint set ignore-prologue-end-flag
+@cindex prologue-end
+@item maint set ignore-prologue-end-flag [on|off]
+Enable or disable the use of the @samp{PROLOGUE-END} flag from the line-table.
+When @samp{off} (the default), @value{GDBN} uses the @samp{PROLOGUE-END} flag
+to place breakpoints past the end of a function prologue. When @samp{on},
+@value{GDBN} ignores the flag and relies on prologue analyzers to skip function
+prologues.
+
+@kindex maint show ignore-prologue-end-flag
+@item maint show ignore-prologue-end-flag
+Show whether @value{GDBN} will ignore the @samp{PROLOGUE-END} flag.
+
@end table
@node Altering
@table @code
@kindex jump
@kindex j @r{(@code{jump})}
-@item jump @var{location}
-@itemx j @var{location}
-Resume execution at @var{location}. Execution stops again immediately
-if there is a breakpoint there. @xref{Specify Location}, for a description
-of the different forms of @var{location}. It is common
-practice to use the @code{tbreak} command in conjunction with
-@code{jump}. @xref{Set Breaks, ,Setting Breakpoints}.
+@item jump @var{locspec}
+@itemx j @var{locspec}
+Resume execution at the address of the code location that results from
+resolving @var{locspec}.
+@xref{Location Specifications}, for a description of the different
+forms of @var{locspec}. If @var{locspec} resolves to more than one
+address, the command aborts before jumping.
+Execution stops again immediately if there is a breakpoint there. It
+is common practice to use the @code{tbreak} command in conjunction
+with @code{jump}. @xref{Set Breaks, ,Setting Breakpoints}.
The @code{jump} command does not change the current stack frame, or
the stack pointer, or the contents of any memory location or any
-register other than the program counter. If @var{location} is in
-a different function from the one currently executing, the results may
-be bizarre if the two functions expect different patterns of arguments or
-of local variables. For this reason, the @code{jump} command requests
-confirmation if the specified line is not in the function currently
-executing. However, even bizarre results are predictable if you are
-well acquainted with the machine-language code of your program.
+register other than the program counter. If @var{locspec} resolves to
+an address in a different function from the one currently executing, the
+results may be bizarre if the two functions expect different patterns
+of arguments or of local variables. For this reason, the @code{jump}
+command requests confirmation if the jump address is not in the
+function currently executing. However, even bizarre results are
+predictable if you are well acquainted with the machine-language code
+of your program.
@end table
On many systems, you can get much the same effect as the @code{jump}
need to resolve the type can be achieved.
@smallexample
-(gdb) compile code static struct a @{ int a; @} v = @{ 42 @}; argv = &v;
-(gdb) compile code printf ("%d\n", ((struct a *) argv)->a);
+(@value{GDBP}) compile code static struct a @{ int a; @} v = @{ 42 @}; argv = &v;
+(@value{GDBP}) compile code printf ("%d\n", ((struct a *) argv)->a);
gdb command line:1:36: error: dereferencing pointer to incomplete type ‘struct a’
Compilation failed.
-(gdb) compile code struct a @{ int a; @}; printf ("%d\n", ((struct a *) argv)->a);
+(@value{GDBP}) compile code struct a @{ int a; @}; printf ("%d\n", ((struct a *) argv)->a);
42
@end smallexample
that lies within the boundaries of this symbol file in memory. Example:
@smallexample
-(gdb) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480
+(@value{GDBP}) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480
add symbol table from file "/home/user/gdb/mylib.so" at
.text_addr = 0x7ffff7ff9480
(y or n) y
Reading symbols from /home/user/gdb/mylib.so...
-(gdb) remove-symbol-file -a 0x7ffff7ff9480
+(@value{GDBP}) remove-symbol-file -a 0x7ffff7ff9480
Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y
-(gdb)
+(@value{GDBP})
@end smallexample
@menu
* Connecting:: Connecting to a remote target
* File Transfer:: Sending files to a remote system
-* Server:: Using the gdbserver program
+* Server:: Using the gdbserver program
* Remote Configuration:: Remote configuration
* Remote Stub:: Implementing a remote stub
@end menu
with ssh:
@smallexample
-(gdb) target remote | ssh -T hostname gdbserver - hello
+(@value{GDBP}) target remote | ssh -T hostname gdbserver - hello
@end smallexample
The @samp{-T} option to ssh is provided because we don't need a remote pty,
@value{GDBN} developers.
For each packet @var{name}, the command to enable or disable the
-packet is @code{set remote @var{name}-packet}. The available settings
-are:
+packet is @code{set remote @var{name}-packet}. If you configure a packet, the
+configuration will apply for all future remote targets if no target is selected.
+In case there is a target selected, only the configuration of the current target
+is changed. All other existing remote targets' features are not affected.
+The command to print the current configuration of a packet is
+@code{show remote @var{name}-packet}. It displays the current remote target's
+configuration. If no remote target is selected, the default configuration for
+future connections is shown. The available settings are:
@multitable @columnfractions 0.28 0.32 0.25
@item Command Name
@end multitable
+@cindex packet size, remote, configuring
+The number of bytes per memory-read or memory-write packet for a remote target
+can be configured using the commands
+@w{@code{set remote memory-read-packet-size}} and
+@w{@code{set remote memory-write-packet-size}}. If set to @samp{0} (zero) the
+default packet size will be used. The actual limit is further reduced depending
+on the target. Specify @samp{fixed} to disable the target-dependent restriction
+and @samp{limit} to enable it. Similar to the enabling and disabling of remote
+packets, the command applies to the currently selected target (if available).
+If no remote target is selected, it applies to all future remote connections.
+The configuration of the selected target can be displayed using the commands
+@w{@code{show remote memory-read-packet-size}} and
+@w{@code{show remote memory-write-packet-size}}. If no remote target is
+selected, the default configuration for future connections is shown.
+
@node Remote Stub
@section Implementing a Remote Stub
subroutines:
@table @code
-@item set_debug_traps
@findex set_debug_traps
+@item set_debug_traps
@cindex remote serial stub, initialization
This routine arranges for @code{handle_exception} to run when your
program stops. You must call this subroutine explicitly in your
program's startup code.
-@item handle_exception
@findex handle_exception
+@item handle_exception
@cindex remote serial stub, main routine
This is the central workhorse, but your program never calls it
explicitly---the setup code arranges for @code{handle_exception} to
serial port.
@table @code
-@item int getDebugChar()
@findex getDebugChar
+@item int getDebugChar()
Write this subroutine to read a single character from the serial port.
It may be identical to @code{getchar} for your target system; a
different name is used to allow you to distinguish the two if you wish.
-@item void putDebugChar(int)
@findex putDebugChar
+@item void putDebugChar(int)
Write this subroutine to write a single character to the serial port.
It may be identical to @code{putchar} for your target system; a
different name is used to allow you to distinguish the two if you wish.
Other routines you need to supply are:
@table @code
-@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
@findex exceptionHandler
+@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
Write this function to install @var{exception_address} in the exception
handling tables. You need to do this because the stub does not have any
way of knowing what the exception handling tables on your target system
@sc{sparc} and 68k stubs are able to mask interrupts themselves without
help from @code{exceptionHandler}.
-@item void flush_i_cache()
@findex flush_i_cache
+@item void flush_i_cache()
On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the
instruction cache, if any, on your target machine. If there is no
instruction cache, this subroutine may be a no-op.
You must also make sure this library routine is available:
@table @code
-@item void *memset(void *, int, int)
@findex memset
+@item void *memset(void *, int, int)
This is the standard library function @code{memset} that sets an area of
memory to a known value. If you have one of the free versions of
@code{libc.a}, @code{memset} can be found there; otherwise, you must
configurations.
@menu
-* BSD libkvm Interface:: Debugging BSD kernel memory images
+* BSD libkvm Interface:: Debugging BSD kernel memory images
* Process Information:: Process information
* DJGPP Native:: Features specific to the DJGPP port
-* Cygwin Native:: Features specific to the Cygwin 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
+* Darwin:: Features specific to Darwin
+* FreeBSD:: Features specific to FreeBSD
@end menu
@node BSD libkvm Interface
tty for standard input and output as well as two network sockets:
@smallexample
-(gdb) info proc files 22136
+(@value{GDBP}) info proc files 22136
process 22136
Open files:
* ARM:: ARM
* BPF:: eBPF
* M68K:: Motorola M68K
-* MicroBlaze:: Xilinx MicroBlaze
+* MicroBlaze:: Xilinx MicroBlaze
* MIPS Embedded:: MIPS Embedded
* OpenRISC 1000:: OpenRISC 1000 (or1k)
* PowerPC Embedded:: PowerPC Embedded
@item show arm force-mode
Show the current forced instruction mode.
+@item set arm unwind-secure-frames
+This command enables unwinding from Non-secure to Secure mode on
+Cortex-M with Security extension.
+This can trigger security exceptions when unwinding the exception
+stack.
+It is enabled by default.
+
+@item show arm unwind-secure-frames
+Show whether unwinding from Non-secure to Secure mode is enabled.
+
@item set debug arm
Toggle whether to display ARM-specific debugging messages from the ARM
target support subsystem.
PowerPC embedded processors support hardware accelerated
@dfn{ranged breakpoints}. A ranged breakpoint stops execution of
the inferior whenever it executes an instruction at any address within
-the range it specifies. To set a ranged breakpoint in @value{GDBN},
+the range it was set at. To set a ranged breakpoint in @value{GDBN},
use the @code{break-range} command.
@value{GDBN} provides the following PowerPC-specific commands:
@table @code
@kindex break-range
-@item break-range @var{start-location}, @var{end-location}
-Set a breakpoint for an address range given by
-@var{start-location} and @var{end-location}, which can specify a function name,
-a line number, an offset of lines from the current line or from the start
-location, or an address of an instruction (see @ref{Specify Location},
-for a list of all the possible ways to specify a @var{location}.)
-The breakpoint will stop execution of the inferior whenever it
-executes an instruction at any address within the specified range,
-(including @var{start-location} and @var{end-location}.)
+@item break-range @var{start-locspec}, @var{end-locspec}
+Set a breakpoint for an address range given by @var{start-locspec} and
+@var{end-locspec}, which are location specs. @xref{Location
+Specifications}, for a list of all the possible forms of location
+specs. @value{GDBN} resolves both @var{start-locspec} and
+@var{end-locspec}, and uses the addresses of the resolved code
+locations as start and end addresses of the range to break at. The
+breakpoint will stop execution of the inferior whenever it executes an
+instruction at any address between the start and end addresses,
+inclusive. If either @var{start-locspec} or @var{end-locspec} resolve
+to multiple code locations in the program, then the command aborts
+with an error without creating a breakpoint.
@kindex set powerpc
@item set powerpc soft-float
* Nios II::
* Sparc64::
* S12Z::
+* AMD GPU:: @acronym{AMD GPU} architectures
@end menu
@node AArch64
@subsubsection AArch64 Pointer Authentication.
@cindex AArch64 Pointer Authentication.
+@anchor{AArch64 PAC}
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
option @code{PR_SET_TAGGED_ADDR_CTRL}. For further information, see the
documentation in the Linux kernel.
+@value{GDBN} supports dumping memory tag data to core files through the
+@command{gcore} command and reading memory tag data from core files generated
+by the @command{gcore} command or the Linux kernel.
+
+When a process uses memory-mapped pages protected by memory tags (for
+example, AArch64 MTE), this additional information will be recorded in
+the core file in the event of a crash or if @value{GDBN} generates a core file
+from the current process state.
+
+The memory tag data will be used so developers can display the memory
+tags from a particular memory region (using the @samp{m} modifier to the
+@command{x} command, using the @command{print} command or using the various
+@command{memory-tag} subcommands.
+
+In the case of a crash, @value{GDBN} will attempt to retrieve the memory tag
+information automatically from the core file, and will show one of the above
+messages depending on whether the synchronous or asynchronous mode is selected.
+@xref{Memory Tagging}. @xref{Memory}.
+
@node i386
@subsection x86 Architecture-specific Issues
BDCCSR register.
@end table
+@node AMD GPU
+@subsection @acronym{AMD GPU}
+@cindex @acronym{AMD GPU} support
+
+@value{GDBN} supports debugging programs offloaded to @acronym{AMD GPU} devices
+using the @url{https://docs.amd.com/, @acronym{AMD ROCm}} platform.
+@value{GDBN} presents host threads alongside GPU wavefronts, allowing debugging
+both the host and device parts of the program simultaneously.
+
+@subsubsection @acronym{AMD GPU} Architectures
+
+The list of @acronym{AMD GPU} architectures supported by @value{GDBN} depends
+on the version of the AMD Debugger API library used. See its
+@uref{https://docs.amd.com/bundle/ROCDebugger_User_and_API, documentation} for
+more details.
+
+@subsubsection @acronym{AMD GPU} Device Driver and @acronym{AMD ROCm} Runtime
+
+@value{GDBN} requires a compatible @acronym{AMD GPU} device driver to
+be installed. A warning message is displayed if either the device
+driver version or the version of the debug support it implements is
+unsupported. @value{GDBN} will continue to function except no
+@acronym{AMD GPU} debugging will be possible.
+
+@value{GDBN} requires each agent to have compatible firmware installed
+by the device driver. A warning message is displayed if unsupported
+firmware is detected. @value{GDBN} will continue to function except
+no @acronym{AMD GPU} debugging will be possible on the agent.
+
+@value{GDBN} requires a compatible @acronym{AMD ROCm} runtime to be
+loaded in order to detect @acronym{AMD GPU} code objects and
+wavefronts. A warning message is displayed if an unsupported
+@acronym{AMD ROCm} runtime is detected, or there is an error or
+restriction that prevents debugging. @value{GDBN} will continue to
+function except no @acronym{AMD GPU} debugging will be possible.
+
+@subsubsection @acronym{AMD GPU} Wavefronts
+@cindex wavefronts
+
+An @acronym{AMD GPU} wavefront is represented in @value{GDBN} as a
+thread.
+
+Note that some @acronym{AMD GPU} architectures may have restrictions
+on providing information about @acronym{AMD GPU} wavefronts created
+when @value{GDBN} is not attached (@pxref{AMD GPU Attaching
+Restrictions, , @acronym{AMD GPU} Attaching Restrictions}).
+
+When scheduler-locking is in effect (@pxref{set scheduler-locking}),
+new wavefronts created by the resumed thread (either CPU thread or GPU
+wavefront) are held in the halt state.
+
+@subsubsection @acronym{AMD GPU} Code Objects
+
+The @samp{info sharedlibrary} command will show the @acronym{AMD GPU}
+code objects as file or memory URIs, together with the host's shared
+libraries. For example:
+
+@smallexample
+(@value{GDBP}) info sharedlibrary
+From To Syms Read Shared Object Library
+0x1111 0x2222 Yes (*) /lib64/ld-linux-x86-64.so.2
+...
+0x3333 0x4444 Yes (*) /opt/rocm-4.5.0/.../libamd_comgr.so
+0x5555 0x6666 Yes (*) /lib/x86_64-linux-gnu/libtinfo.so.5
+0x7777 0x8888 Yes file:///tmp/a.out#offset=6477&size=10832
+0x9999 0xaaaa Yes (*) memory://95557/mem#offset=0x1234&size=100
+(*): Shared library is missing debugging information.
+(@value{GDBP})
+@end smallexample
+
+For a @samp{file} URI, the path portion is the file on disk containing
+the code object. The @var{offset} parameter is a 0-based offset in
+this file, to the start of the code object. If omitted, it defaults to
+0. The @var{size} parameter is the size of the code object in bytes.
+If omitted, it defaults to the size of the file.
+
+For a @samp{memory} URI, the path portion is the process id of the
+process owning the memory containing the code object. The @var{offset}
+parameter is the memory address where the code object is found, and
+the @var{size} parameter is its size in bytes.
+
+@acronym{AMD GPU} code objects are loaded into each @acronym{AMD GPU}
+device separately. The @samp{info sharedlibrary} command may
+therefore show the same code object loaded multiple times. As a
+consequence, setting a breakpoint in @acronym{AMD GPU} code will
+result in multiple breakpoint locations if there are multiple
+@acronym{AMD GPU} devices.
+
+@subsubsection @acronym{AMD GPU} Entity Target Identifiers and Convenience Variables
+
+The @acronym{AMD GPU} entities have the following target identifier formats:
+
+@table @asis
+
+@item Thread Target ID
+The @acronym{AMD GPU} thread target identifier (@var{systag}) string has the
+following format:
+
+@smallexample
+AMDGPU Wave @var{agent-id}:@var{queue-id}:@var{dispatch-id}:@var{wave-id} (@var{work-group-x},@var{work-group-y},@var{work-group-z})/@var{work-group-thread-index}
+@end smallexample
+
+@end table
+
+@anchor{AMD GPU Signals}
+@subsubsection @acronym{AMD GPU} Signals
+
+For @acronym{AMD GPU} wavefronts, @value{GDBN} maps target conditions to stop
+signals in the following way:
+
+@table @code
+
+@item SIGILL
+Execution of an illegal instruction.
+
+@item SIGTRAP
+Execution of a @code{S_TRAP} instruction other than:
+
+@itemize @bullet{}
+
+@item
+@code{S_TRAP 1} which is used by @value{GDBN} to insert breakpoints.
+
+@item
+@code{S_TRAP 2} which raises @code{SIGABRT}.
+
+@end itemize
+
+@item SIGABRT
+Execution of a @code{S_TRAP 2} instruction.
+
+@item SIGFPE
+Execution of a floating point or integer instruction detects a
+condition that is enabled to raise a signal. The conditions include:
+
+@itemize @bullet{}
+
+@item
+Floating point operation is invalid.
+
+@item
+Floating point operation had subnormal input that was rounded to zero.
+
+@item
+Floating point operation performed a division by zero.
+
+@item
+Floating point operation produced an overflow result. The result was
+rounded to infinity.
+
+@item
+Floating point operation produced an underflow result. A subnormal
+result was rounded to zero.
+
+@item
+Floating point operation produced an inexact result.
+
+@item
+Integer operation performed a division by zero.
+
+@end itemize
+
+By default, these conditions are not enabled to raise signals. The
+@samp{set $mode} command can be used to change the @acronym{AMD GPU}
+wavefront's register that has bits controlling which conditions are
+enabled to raise signals. The @samp{print $trapsts} command can be
+used to inspect which conditions have been detected even if they are
+not enabled to raise a signal.
+
+@item SIGBUS
+Execution of an instruction that accessed global memory using an
+address that is outside the virtual address range.
+
+@item SIGSEGV
+Execution of an instruction that accessed a global memory page that is
+either not mapped or accessed with incompatible permissions.
+
+@end table
+
+If a single instruction raises more than one signal, they will be
+reported one at a time each time the wavefront is continued.
+
+@subsubsection @acronym{AMD GPU} Logging
+
+The @samp{set debug amd-dbgapi} command can be used
+to enable diagnostic messages in the @samp{amd-dbgapi} target. The
+@samp{show debug amd-dbgapi} command displays the current setting.
+@xref{set debug amd-dbgapi}.
+
+The @samp{set debug amd-dbgapi-lib log-level @var{level}} command can be used
+to enable diagnostic messages from the @samp{amd-dbgapi} library (which
+@value{GDBN} uses under the hood). The @samp{show debug amd-dbgapi-lib
+log-level} command displays the current @samp{amd-dbgapi} library log level.
+@xref{set debug amd-dbgapi-lib}.
+
+@subsubsection @acronym{AMD GPU} Restrictions
+
+@enumerate
+
+@item
+When in non-stop mode, wavefronts may not hit breakpoints inserted
+while not stopped, nor see memory updates made while not stopped,
+until the wavefront is next stopped. Memory updated by non-stopped
+wavefronts may not be visible until the wavefront is next stopped.
+
+@item The HIP runtime performs deferred code object loading by default.
+@acronym{AMD GPU} code objects are not loaded until the first kernel is
+launched. Before then, all breakpoints have to be set as pending breakpoints.
+
+If source line positions are used that only correspond to source lines in
+unloaded code objects, then @value{GDBN} may not set pending breakpoints, and
+instead set breakpoints on the next following source line that maps to host
+code. This can result in unexpected breakpoint hits being reported. When the
+code object containing the source lines is loaded, the incorrect breakpoints
+will be removed and replaced by the correct ones. This problem can be avoided
+by only setting breakpoints in unloaded code objects using symbol or function
+names.
+
+Setting the @code{HIP_ENABLE_DEFERRED_LOADING} environment variable to @code{0}
+can be used to disable deferred code object loading by the HIP runtime. This
+ensures all code objects will be loaded when the inferior reaches the beginning
+of the @code{main} function.
+
+@item
+If no CPU thread is running, then @samp{Ctrl-C} is not able to stop
+@acronym{AMD GPU} threads. This can happen for example if you enable
+@code{scheduler-locking} after the whole program stopped, and then resume an
+@acronym{AMD GPU} thread. The only way to unblock the situation is to kill the
+@value{GDBN} process.
+
+@anchor{AMD GPU Attaching Restrictions}
+@item
+
+By default, for some architectures, the @acronym{AMD GPU} device driver causes
+all @acronym{AMD GPU} wavefronts created when @value{GDBN} is not attached to
+be unable to report the dispatch associated with the wavefront, or the
+wavefront's work-group position. The @samp{info threads} command will display
+this missing information with a @samp{?}.
+
+This does not affect wavefronts created while @value{GDBN} is attached which
+are always capable of reporting this information.
+
+If the @env{HSA_ENABLE_DEBUG} environment variable is set to @samp{1} when the
+@acronym{AMD ROCm} runtime is initialized, then this information will be
+available for all architectures even for wavefronts created when @value{GDBN}
+was not attached.
+
+@end enumerate
@node Controlling GDB
@chapter Controlling @value{GDBN}
For example:
@smallexample
-set extended-prompt Current working directory: \w (gdb)
+set extended-prompt Current working directory: \w (@value{GDBP})
@end smallexample
Note that when an extended-prompt is set, it takes control of the
@item show style sources
Show the current state of source code styling.
+@item set style tui-current-position @samp{on|off}
+Enable or disable styling of the source and assembly code highlighted
+by the TUI's current position indicator. The default is @samp{off}.
+@xref{TUI, ,@value{GDBN} Text User Interface}.
+
+@item show style tui-current-position
+Show whether the source and assembly code highlighted by the TUI's
+current position indicator is styled.
+
+@anchor{style_disassembler_enabled}
@item set style disassembler enabled @samp{on|off}
Enable or disable disassembler styling. This affects whether
disassembler output, such as the output of the @code{disassemble}
general is enabled (with @code{set style enabled on}), and if a source
highlighting library is available to @value{GDBN}.
-To highlight disassembler output, @value{GDBN} must be compiled with
-Python support, and the Python Pygments package must be available. If
-these requirements are not met then @value{GDBN} will not highlight
-disassembler output, even when this option is @samp{on}.
+The two source highlighting libraries that @value{GDBN} could use to
+style disassembler output are; @value{GDBN}'s builtin disassembler, or
+the Python Pygments package.
+
+@value{GDBN}'s first choice will be to use the builtin disassembler
+for styling, this usually provides better results, being able to style
+different types of instruction operands differently. However, the
+builtin disassembler is not able to style all architectures.
+
+For architectures that the builtin disassembler is unable to style,
+@value{GDBN} will fall back to use the Python Pygments package where
+possible. In order to use the Python Pygments package, @value{GDBN}
+must be built with Python support, and the Pygments package must be
+installed.
+
+If neither of these options are available then @value{GDBN} will
+produce unstyled disassembler output, even when this setting is
+@samp{on}.
+
+To discover if the current architecture supports styling using the
+builtin disassembler library see @ref{maint_libopcodes_styling,,@kbd{maint
+show libopcodes-styling enabled}}.
@item show style disassembler enabled
Show the current state of disassembler styling.
+
@end table
Subcommands of @code{set style} control specific forms of styling.
The style-able objects are:
@table @code
@item filename
-Control the styling of file names. By default, this style's
+Control the styling of file names and URLs. By default, this style's
foreground color is green.
@item function
@code{set style function} family of commands. By default, this
style's foreground color is yellow.
+This style is also used for symbol names in styled disassembler output
+if @value{GDBN} is using its builtin disassembler library for styling
+(@pxref{style_disassembler_enabled,,@kbd{set style disassembler
+enabled}}).
+
@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
@code{set style address} family of commands. By default, this style's
foreground color is blue.
+This style is also used for addresses in styled disassembler output
+if @value{GDBN} is using its builtin disassembler library for styling
+(@pxref{style_disassembler_enabled,,@kbd{set style disassembler
+enabled}}).
+
@item version
Control the styling of @value{GDBN}'s version number text. By
default, this style's foreground color is magenta and it has bold
the command @command{apropos -v REGEXP} uses the highlight style to
mark the documentation parts matching @var{regexp}.
+@item metadata
+Control the styling of data annotations added by @value{GDBN} to data
+it displays. By default, this style's intensity is dim. Metadata
+annotations include the @samp{repeats @var{n} times} annotation for
+suppressed display of repeated array elements (@pxref{Print Settings}),
+@samp{<unavailable>} and @w{@samp{<error @var{descr}>}} annotations
+for errors and @samp{<optimized-out>} annotations for optimized-out
+values in displaying stack frame information in backtraces
+(@pxref{Backtrace}), etc.
+
@item tui-border
Control the styling of the TUI border. Note that, unlike other
styling options, only the color of the border can be controlled via
Control the styling of the active TUI border; that is, the TUI window
that has the focus.
+@item disassembler comment
+Control the styling of comments in the disassembler output. These are
+managed with the @code{set style disassembler comment} family of
+commands. This style is only used when @value{GDBN} is styling using
+its builtin disassembler library
+(@pxref{style_disassembler_enabled,,@kbd{set style disassembler
+enabled}}). By default, this style's intensity is dim, and its
+foreground color is white.
+
+@item disassembler immediate
+Control the styling of numeric operands in the disassembler output.
+These are managed with the @code{set style disassembler immediate}
+family of commands. This style is not used for instruction operands
+that represent addresses, in that case the @samp{disassembler address}
+style is used. This style is only used when @value{GDBN} is styling
+using its builtin disassembler library. By default, this style's
+foreground color is blue.
+
+@item disassembler address
+Control the styling of address operands in the disassembler output.
+This is an alias for the @samp{address} style.
+
+@item disassembler symbol
+Control the styling of symbol names in the disassembler output. This
+is an alias for the @samp{function} style.
+
+@item disassembler mnemonic
+Control the styling of instruction mnemonics in the disassembler
+output. These are managed with the @code{set style disassembler
+mnemonic} family of commands. This style is also used for assembler
+directives, e.g.@: @code{.byte}, @code{.word}, etc. This style is
+only used when @value{GDBN} is styling using its builtin disassembler
+library. By default, this style's foreground color is green.
+
+@item disassembler register
+Control the styling of register operands in the disassembler output.
+These are managed with the @code{set style disassembler register}
+family of commands. This style is only used when @value{GDBN} is
+styling using its builtin disassembler library. By default, this style's
+foreground color is red.
+
@end table
@node Numbers
or disabled.
@smallexample
-(gdb) show auto-load
+(@value{GDBP}) show auto-load
gdb-scripts: Auto-loading of canned sequences of commands scripts is on.
libthread-db: Auto-loading of inferior specific libthread_db is on.
local-gdbinit: Auto-loading of .gdbinit script from current directory
not.
@smallexample
-(gdb) info auto-load
+(@value{GDBP}) info auto-load
gdb-scripts:
Loaded Script
Yes /home/user/gdb/gdb-gdb.gdb
may not be too obvious while setting it up.
@smallexample
-(gdb) set debug auto-load on
-(gdb) file ~/src/t/true
+(@value{GDBP}) set debug auto-load on
+(@value{GDBP}) file ~/src/t/true
auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb"
for objfile "/tmp/true".
auto-load: Updating directories of "/usr:/opt".
@item show debug arch
Displays the current state of displaying gdbarch debugging info.
-@item set debug aix-solib
-@cindex AIX shared library debugging
-Control display of debugging messages from the AIX shared library
-support module. The default is off.
-@item show debug aix-solib
-Show the current state of displaying AIX shared library debugging messages.
-
@item set debug aix-thread
@cindex AIX threads
Display debugging messages about inner workings of the AIX thread
@item show debug aix-thread
Show the current state of AIX thread debugging info display.
+@cindex AMD GPU debugging info
+@anchor{set debug amd-dbgapi-lib}
+@item set debug amd-dbgapi-lib
+@itemx show debug amd-dbgapi-lib
+
+The @code{set debug amd-dbgapi-lib log-level @var{level}} command can be used
+to enable diagnostic messages from the @samp{amd-dbgapi} library, where
+@var{level} can be:
+
+@table @code
+
+@item off
+no logging is enabled
+
+@item error
+fatal errors are reported
+
+@item warning
+fatal errors and warnings are reported
+
+@item info
+fatal errors, warnings, and info messages are reported
+
+@item verbose
+all messages are reported
+
+@end table
+
+The @code{show debug amd-dbgapi-lib log-level} command displays the current
+@acronym{amd-dbgapi} library log level.
+
+@anchor{set debug amd-dbgapi}
+@item set debug amd-dbgapi
+@itemx show debug amd-dbgapi
+
+The @samp{set debug amd-dbgapi} command can be used
+to enable diagnostic messages in the @samp{amd-dbgapi} target. The
+@samp{show debug amd-dbgapi} command displays the current setting.
+@xref{set debug amd-dbgapi}.
+
@item set debug check-physname
@cindex physname
Check the results of the ``physname'' computation. When reading DWARF
@item show debug infrun
Displays the current state of @value{GDBN} inferior debugging.
+@item set debug infcall
+@cindex inferior function call debugging info
+Turns on or off display of debugging info related to inferior function
+calls made by @value{GDBN}.
+@item show debug infcall
+Displays the current state of @value{GDBN} inferior function call debugging.
+
@item set debug jit
@cindex just-in-time compilation, debugging messages
Turn on or off debugging messages from JIT debug support.
Displays the current state of displaying @value{GDBN} serial debugging
info.
-@item set debug solib-frv
-@cindex FR-V shared-library debugging
-Turn on or off debugging messages for FR-V shared-library code.
-@item show debug solib-frv
-Display the current state of FR-V shared-library code debugging
-messages.
+@item set debug solib
+Turns on or off display of debugging messages related to shared libraries.
+The default is off.
+@item show debug solib
+Show the current state of solib debugging messages.
@item set debug symbol-lookup
@cindex symbol lookup
documentation of a command. Redefining the command with @code{define}
does not change the documentation.
+It is also possible to document user-defined aliases. The alias documentation
+will then be used by the @code{help} and @code{apropos} commands
+instead of the documentation of the aliased command.
+Documenting a user-defined alias is particularly useful when defining
+an alias as a set of nested @code{with} commands
+(@pxref{Command aliases default args}).
+
@kindex define-prefix
@item define-prefix @var{commandname}
Define or mark the command @var{commandname} as a user-defined prefix
Example:
@example
-(gdb) define-prefix abc
-(gdb) define-prefix abc def
-(gdb) define abc def
+(@value{GDBP}) define-prefix abc
+(@value{GDBP}) define-prefix abc def
+(@value{GDBP}) define abc def
Type commands for definition of "abc def".
End with a line saying just "end".
>echo command initial def\n
>end
-(gdb) define abc def ghi
+(@value{GDBP}) define abc def ghi
Type commands for definition of "abc def ghi".
End with a line saying just "end".
>echo command ghi\n
>end
-(gdb) define abc def
+(@value{GDBP}) define abc def
Keeping subcommands of prefix command "def".
Redefine command "def"? (y or n) y
Type commands for definition of "abc def".
End with a line saying just "end".
>echo command def\n
>end
-(gdb) abc def ghi
+(@value{GDBP}) abc def ghi
command ghi
-(gdb) abc def
+(@value{GDBP}) abc def
command def
-(gdb)
+(@value{GDBP})
@end example
@kindex dont-repeat
named @samp{di}. The following will accomplish this.
@smallexample
-(gdb) alias -a di = disas
+(@value{GDBP}) alias -a di = disas
@end smallexample
Note that aliases are different from user-defined commands. With a
of a command.
@smallexample
-(gdb) alias -a set print elms = set print elements
-(gdb) alias -a show print elms = show print elements
-(gdb) set p elms 200
-(gdb) show p elms
+(@value{GDBP}) alias -a set print elms = set print elements
+(@value{GDBP}) alias -a show print elms = show print elements
+(@value{GDBP}) set p elms 200
+(@value{GDBP}) show p elms
Limit on string chars or array elements to print is 200.
@end smallexample
@var{alias}, just as they are normally.
@smallexample
-(gdb) alias -a set pr elms = set p ele
+(@value{GDBP}) alias -a set pr elms = set p ele
@end smallexample
Finally, here is an example showing the creation of a one word
This creates alias @samp{spe} of the command @samp{set print elements}.
@smallexample
-(gdb) alias spe = set print elements
-(gdb) spe 20
+(@value{GDBP}) alias spe = set print elements
+(@value{GDBP}) spe 20
@end smallexample
@menu
-* Command aliases default args:: Default arguments for aliases
+* Command aliases default args:: Default arguments for aliases
@end menu
@node Command aliases default args
For more information about the @code{with} command usage,
see @ref{Command Settings}.
+By default, asking the help for an alias shows the documentation of
+the aliased command. When the alias is a set of nested commands, @code{help}
+of an alias shows the documentation of the first command. This help
+is not particularly useful for an alias such as @code{pp10}.
+For such an alias, it is useful to give a specific documentation
+using the @code{document} command (@pxref{Define, document}).
+
+
@c Python docs live in a separate file.
@include python.texi
@code{auto-load safe-path} (@pxref{Auto-loading safe path}).
@menu
-* objfile-gdbdotext file:: The @file{@var{objfile}-gdb.@var{ext}} file
-* dotdebug_gdb_scripts section:: The @code{.debug_gdb_scripts} section
-* Which flavor to choose?:: Choosing between these approaches
+* objfile-gdbdotext file:: The @file{@var{objfile}-gdb.@var{ext}} file
+* dotdebug_gdb_scripts section:: The @code{.debug_gdb_scripts} section
+* Which flavor to choose?:: Choosing between these approaches
@end menu
@node objfile-gdbdotext file
used interpreter with @value{GDBN}. With no interpreter specified at runtime,
@value{GDBN} will use this interpreter.
+@item dap
+@cindex DAP
+@cindex Debugger Adapter Protocol
+When @value{GDBN} has been built with Python support, it also supports
+the Debugger Adapter Protocol. This protocol can be used by a
+debugger GUI or an IDE to communicate with @value{GDBN}. This
+protocol is documented at
+@url{https://microsoft.github.io/debug-adapter-protocol/}.
+
@item mi
@cindex mi interpreter
The newest @sc{gdb/mi} interface (currently @code{mi3}). Used primarily
@cindex mi2 interpreter
The @sc{gdb/mi} interface introduced in @value{GDBN} 6.0.
-@item mi1
-@cindex mi1 interpreter
-The @sc{gdb/mi} interface introduced in @value{GDBN} 5.1.
-
@end table
@cindex invoke another interpreter
when their values change.
@end table
-The source and assembly windows show the current program position
-by highlighting the current line and marking it with a @samp{>} marker.
+The source and assembly windows show the current program position by
+highlighting the current line and marking it with a @samp{>} marker.
+By default, source and assembly code styling is disabled for the
+highlighted text, but you can enable it with the @code{set style
+tui-current-position on} command. @xref{Output Styling}.
+
Breakpoints are indicated with two markers. The first marker
indicates the breakpoint type:
width of the terminal. Because they have weight 2, the source and
assembly windows will be twice the height of the command window.
-@item layout @var{name}
+@kindex tui layout
@kindex layout
+@item tui layout @var{name}
+@itemx layout @var{name}
Changes which TUI windows are displayed. The @var{name} parameter
controls which layout is shown. It can be either one of the built-in
layout names, or the name of a layout defined by the user using
register, assembler, and command windows.
@end table
-@item focus @var{name}
@kindex focus
+@item tui focus @var{name}
+@itemx focus @var{name}
Changes which TUI window is currently active for scrolling. The
@var{name} parameter can be any of the following:
Make the command window active for scrolling.
@end table
-@item refresh
+@kindex tui refresh
@kindex refresh
+@item tui refresh
+@itemx refresh
Refresh the screen. This is similar to typing @kbd{C-L}.
@item tui reg @var{group}
@kindex update
Update the source window and the current execution point.
-@item winheight @var{name} +@var{count}
-@itemx winheight @var{name} -@var{count}
+@kindex tui window height
@kindex winheight
+@item tui window height @var{name} +@var{count}
+@itemx tui window height @var{name} -@var{count}
+@itemx winheight @var{name} +@var{count}
+@itemx winheight @var{name} -@var{count}
Change the height of the window @var{name} by @var{count} lines.
Positive counts increase the height, while negative counts decrease
it. The @var{name} parameter can be the name of any currently visible
window. The names of the currently visible windows can be discovered
using @kbd{info win} (@pxref{info_win_command,,info win}).
+
+The set of currently visible windows must always fill the terminal,
+and so, it is only possible to resize on window if there are other
+visible windows that can either give or receive the extra terminal
+space.
+
+@kindex tui window width
+@kindex winwidth
+@item tui window width @var{name} +@var{count}
+@itemx tui window width @var{name} -@var{count}
+@itemx winwidth @var{name} +@var{count}
+@itemx winwidth @var{name} -@var{count}
+Change the width of the window @var{name} by @var{count} columns.
+Positive counts increase the width, while negative counts decrease it.
+The @var{name} parameter can be the name of any currently visible
+window. The names of the currently visible windows can be discovered
+using @code{info win} (@pxref{info_win_command,,info win}).
+
+The set of currently visible windows must always fill the terminal,
+and so, it is only possible to resize on window if there are other
+visible windows that can either give or receive the extra terminal
+space.
@end table
@node TUI Configuration
source text at the next tab stop; the compact display uses only as
much space as is needed for the line numbers in the current file, and
only a single space to separate the line numbers from the source.
+
+@kindex set debug tui
+@item set debug tui @r{[}on|off@r{]}
+Turn on or off display of @value{GDBN} internal debug messages relating
+to the TUI.
+
+@kindex show debug tui
+@item show debug tui
+Show the current status of displaying @value{GDBN} internal debug
+messages relating to the TUI.
+
@end table
Note that the colors of the TUI borders can be controlled using the
@code{( @var{group} )+} means that @var{group} inside the parentheses
may repeat one or more times.
+@item
+@code{( @var{group} )} means that @var{group} inside the parentheses
+occurs exactly once.
+
@item
@code{"@var{string}"} means a literal @var{string}.
@end itemize
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
+@multitable @columnfractions .1 .1 .8
@headitem MI version @tab GDB version @tab Breaking changes
@item
is a list.
@end itemize
+@item
+@center 4
+@tab
+@center 13.1
+@tab
+
+@itemize
+@item
+The syntax of the "script" field in breakpoint output has changed in the
+responses to the @code{-break-insert} and @code{-break-info} commands, as
+well as the @code{=breakpoint-created} and @code{=breakpoint-modified}
+events. The previous output was syntactically invalid. The new output is
+a list.
+@end itemize
+
@end multitable
If your front end cannot yet migrate to a more recent version of the
@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
+MI 3, even when using MI versions below 3. This command has no
effect when using MI version 3 or later.
+@item -fix-breakpoint-script-output
+Use the output for the breakpoint "script" field which was introduced by
+MI 4, even when using MI versions below 4. This command has no effect when
+using MI version 4 or later.
+
@end table
The best way to avoid unexpected changes in MI that might break your front
The synchronous operation was successful, @code{@var{results}} are the return
values.
-@item "^running"
@findex ^running
+@item "^running"
This result record is equivalent to @samp{^done}. Historically, it
was output instead of @samp{^done} if the command has resumed the
target. This behaviour is maintained for backward compatibility, but
identically and rely on the @samp{*running} output record to determine
which threads are resumed.
-@item "^connected"
@findex ^connected
+@item "^connected"
@value{GDBN} has connected to a remote target.
-@item "^error" "," "msg=" @var{c-string} [ "," "code=" @var{c-string} ]
@findex ^error
+@item "^error" "," "msg=" @var{c-string} [ "," "code=" @var{c-string} ]
The operation failed. The @code{msg=@var{c-string}} variable contains
the corresponding error message.
Indicates that the command causing the error does not exist.
@end table
-@item "^exit"
@findex ^exit
+@item "^exit"
@value{GDBN} has terminated.
@end table
@item exec
The inferior called @code{exec}. This is reported when @code{catch exec}
(@pxref{Set Catchpoints}) has been used.
+@item no-history
+There isn't enough history recorded to continue reverse execution.
@end table
The @var{id} field identifies the global thread ID of the thread
This section documents @sc{gdb/mi} commands for manipulating
breakpoints.
-@subheading The @code{-break-after} Command
@findex -break-after
+@subheading The @code{-break-after} Command
@subsubheading Synopsis
@end smallexample
@ignore
-@subheading The @code{-break-catch} Command
@findex -break-catch
+@subheading The @code{-break-catch} Command
@end ignore
-@subheading The @code{-break-commands} Command
@findex -break-commands
+@subheading The @code{-break-commands} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-break-condition} Command
@findex -break-condition
+@subheading The @code{-break-condition} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-break-delete} Command
@findex -break-delete
+@subheading The @code{-break-delete} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-break-disable} Command
@findex -break-disable
+@subheading The @code{-break-disable} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-break-enable} Command
@findex -break-enable
+@subheading The @code{-break-enable} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-break-info} Command
@findex -break-info
+@subheading The @code{-break-info} Command
@subsubheading Synopsis
@subsubheading Example
N.A.
-@subheading The @code{-break-insert} Command
@findex -break-insert
@anchor{-break-insert}
+@subheading The @code{-break-insert} Command
@subsubheading Synopsis
@smallexample
-break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] [ --qualified ]
[ -c @var{condition} ] [ --force-condition ] [ -i @var{ignore-count} ]
- [ -p @var{thread-id} ] [ @var{location} ]
+ [ -p @var{thread-id} ] [ @var{locspec} ]
@end smallexample
@noindent
-If specified, @var{location}, can be one of:
+If specified, @var{locspec}, can be one of:
@table @var
@item linespec location
@item -h
Insert a hardware breakpoint.
@item -f
-If @var{location} cannot be parsed (for example if it
+If @var{locspec} cannot be resolved (for example if it
refers to unknown files or functions), create a pending
-breakpoint. Without this flag, @value{GDBN} will report
-an error, and won't create a breakpoint, if @var{location}
+breakpoint. Without this flag, @value{GDBN} will report
+an error, and won't create a breakpoint, if @var{locspec}
cannot be parsed.
@item -d
Create a disabled breakpoint.
fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"],
times="0"@}]@}
(gdb)
-@c -break-insert -r foo.*
-@c ~int foo(int, int);
-@c ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c,
-@c "fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"],
-@c times="0"@}
-@c (gdb)
@end smallexample
-@subheading The @code{-dprintf-insert} Command
@findex -dprintf-insert
+@subheading The @code{-dprintf-insert} Command
@subsubheading Synopsis
@smallexample
-dprintf-insert [ -t ] [ -f ] [ -d ] [ --qualified ]
[ -c @var{condition} ] [--force-condition] [ -i @var{ignore-count} ]
- [ -p @var{thread-id} ] [ @var{location} ] [ @var{format} ]
+ [ -p @var{thread-id} ] [ @var{locspec} ] [ @var{format} ]
[ @var{argument} ]
@end smallexample
@noindent
-If supplied, @var{location} and @code{--qualified} may be specified
+If supplied, @var{locspec} and @code{--qualified} may be specified
the same way as for the @code{-break-insert} command.
@xref{-break-insert}.
@item -t
Insert a temporary breakpoint.
@item -f
-If @var{location} cannot be parsed (for example, if it
+If @var{locspec} cannot be parsed (for example, if it
refers to unknown files or functions), create a pending
breakpoint. Without this flag, @value{GDBN} will report
-an error, and won't create a breakpoint, if @var{location}
+an error, and won't create a breakpoint, if @var{locspec}
cannot be parsed.
@item -d
Create a disabled breakpoint.
4^done,bkpt=@{number="1",type="dprintf",disp="keep",enabled="y",
addr="0x000000000040061b",func="foo",file="mi-dprintf.c",
fullname="mi-dprintf.c",line="25",thread-groups=["i1"],
-times="0",script=@{"printf \"At foo entry\\n\"","continue"@},
+times="0",script=["printf \"At foo entry\\n\"","continue"],
original-location="foo"@}
(gdb)
5-dprintf-insert 26 "arg=%d, g=%d\n" arg g
5^done,bkpt=@{number="2",type="dprintf",disp="keep",enabled="y",
addr="0x000000000040062a",func="foo",file="mi-dprintf.c",
fullname="mi-dprintf.c",line="26",thread-groups=["i1"],
-times="0",script=@{"printf \"arg=%d, g=%d\\n\", arg, g","continue"@},
+times="0",script=["printf \"arg=%d, g=%d\\n\", arg, g","continue"],
original-location="mi-dprintf.c:26"@}
(gdb)
@end smallexample
-@subheading The @code{-break-list} Command
@findex -break-list
+@subheading The @code{-break-list} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-break-passcount} Command
@findex -break-passcount
+@subheading The @code{-break-passcount} Command
@subsubheading Synopsis
is not a tracepoint, error is emitted. This corresponds to CLI
command @samp{passcount}.
-@subheading The @code{-break-watch} Command
@findex -break-watch
+@subheading The @code{-break-watch} Command
@subsubheading Synopsis
@node Shared Library GDB/MI Catchpoint Commands
@subsection Shared Library @sc{gdb/mi} Catchpoints
-@subheading The @code{-catch-load} Command
@findex -catch-load
+@subheading The @code{-catch-load} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-catch-unload} Command
@findex -catch-unload
+@subheading The @code{-catch-unload} Command
@subsubheading Synopsis
The following @sc{gdb/mi} commands can be used to create catchpoints
that stop the execution when Ada exceptions are being raised.
-@subheading The @code{-catch-assert} Command
@findex -catch-assert
+@subheading The @code{-catch-assert} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-catch-exception} Command
@findex -catch-exception
+@subheading The @code{-catch-exception} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-catch-handlers} Command
@findex -catch-handlers
+@subheading The @code{-catch-handlers} Command
@subsubheading Synopsis
that stop the execution when C@t{++} exceptions are being throw, rethrown,
or caught.
-@subheading The @code{-catch-throw} Command
@findex -catch-throw
+@subheading The @code{-catch-throw} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-catch-rethrow} Command
@findex -catch-rethrow
+@subheading The @code{-catch-rethrow} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-catch-catch} Command
@findex -catch-catch
+@subheading The @code{-catch-catch} Command
@subsubheading Synopsis
@node GDB/MI Program Context
@section @sc{gdb/mi} Program Context
-@subheading The @code{-exec-arguments} Command
@findex -exec-arguments
+@subheading The @code{-exec-arguments} Command
@subsubheading Synopsis
@ignore
-@subheading The @code{-exec-show-arguments} Command
@findex -exec-show-arguments
+@subheading The @code{-exec-show-arguments} Command
@subsubheading Synopsis
@end ignore
-@subheading The @code{-environment-cd} Command
@findex -environment-cd
+@subheading The @code{-environment-cd} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-environment-directory} Command
@findex -environment-directory
+@subheading The @code{-environment-directory} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-environment-path} Command
@findex -environment-path
+@subheading The @code{-environment-path} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-environment-pwd} Command
@findex -environment-pwd
+@subheading The @code{-environment-pwd} Command
@subsubheading Synopsis
@section @sc{gdb/mi} Thread Commands
-@subheading The @code{-thread-info} Command
@findex -thread-info
+@subheading The @code{-thread-info} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-thread-list-ids} Command
@findex -thread-list-ids
+@subheading The @code{-thread-list-ids} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-thread-select} Command
@findex -thread-select
+@subheading The @code{-thread-select} Command
@subsubheading Synopsis
@node GDB/MI Ada Tasking Commands
@section @sc{gdb/mi} Ada Tasking Commands
-@subheading The @code{-ada-task-info} Command
@findex -ada-task-info
+@subheading The @code{-ada-task-info} Command
@subsubheading Synopsis
asynchronously with remote targets and this interaction is mimicked in
other cases.
-@subheading The @code{-exec-continue} Command
@findex -exec-continue
+@subheading The @code{-exec-continue} Command
@subsubheading Synopsis
(gdb)
@end smallexample
+For a @samp{breakpoint-hit} stopped reason, when the breakpoint
+encountered has multiple locations, the field @samp{bkptno} is
+followed by the field @samp{locno}.
+
+@smallexample
+-exec-continue
+^running
+(gdb)
+@@Hello world
+*stopped,reason="breakpoint-hit",disp="keep",bkptno="2",locno="3",frame=@{
+func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c",
+line="13",arch="i386:x86_64"@}
+(gdb)
+@end smallexample
-@subheading The @code{-exec-finish} Command
@findex -exec-finish
+@subheading The @code{-exec-finish} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-exec-interrupt} Command
@findex -exec-interrupt
+@subheading The @code{-exec-interrupt} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-exec-jump} Command
@findex -exec-jump
+@subheading The @code{-exec-jump} Command
@subsubheading Synopsis
@smallexample
- -exec-jump @var{location}
+ -exec-jump @var{locspec}
@end smallexample
-Resumes execution of the inferior program at the location specified by
-parameter. @xref{Specify Location}, for a description of the
-different forms of @var{location}.
+Resumes execution of the inferior program at the address to
+which @var{locspec} resolves. @xref{Location Specifications},
+for a description of the different forms of @var{locspec}.
@subsubheading @value{GDBN} Command
@end smallexample
-@subheading The @code{-exec-next} Command
@findex -exec-next
+@subheading The @code{-exec-next} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-exec-next-instruction} Command
@findex -exec-next-instruction
+@subheading The @code{-exec-next-instruction} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-exec-return} Command
@findex -exec-return
+@subheading The @code{-exec-return} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-exec-run} Command
@findex -exec-run
+@subheading The @code{-exec-run} Command
@subsubheading Synopsis
@c @subheading -exec-signal
-@subheading The @code{-exec-step} Command
@findex -exec-step
+@subheading The @code{-exec-step} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-exec-step-instruction} Command
@findex -exec-step-instruction
+@subheading The @code{-exec-step-instruction} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-exec-until} Command
@findex -exec-until
+@subheading The @code{-exec-until} Command
@subsubheading Synopsis
@smallexample
- -exec-until [ @var{location} ]
+ -exec-until [ @var{locspec} ]
@end smallexample
-Executes the inferior until the @var{location} specified in the
-argument is reached. If there is no argument, the inferior executes
-until a source line greater than the current one is reached. The
-reason for stopping in this case will be @samp{location-reached}.
+Executes the inferior until it reaches the address to which
+@var{locspec} resolves. If there is no argument, the inferior
+executes until it reaches a source line greater than the current one.
+The reason for stopping in this case will be @samp{location-reached}.
@subsubheading @value{GDBN} Command
@node GDB/MI Stack Manipulation
@section @sc{gdb/mi} Stack Manipulation Commands
-@subheading The @code{-enable-frame-filters} Command
@findex -enable-frame-filters
+@subheading The @code{-enable-frame-filters} Command
@smallexample
-enable-frame-filters
Note that if Python support has not been compiled into @value{GDBN},
this command will still succeed (and do nothing).
-@subheading The @code{-stack-info-frame} Command
@findex -stack-info-frame
+@subheading The @code{-stack-info-frame} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-stack-info-depth} Command
@findex -stack-info-depth
+@subheading The @code{-stack-info-depth} Command
@subsubheading Synopsis
@end smallexample
@anchor{-stack-list-arguments}
-@subheading The @code{-stack-list-arguments} Command
@findex -stack-list-arguments
+@subheading The @code{-stack-list-arguments} Command
@subsubheading Synopsis
@anchor{-stack-list-frames}
-@subheading The @code{-stack-list-frames} Command
@findex -stack-list-frames
+@subheading The @code{-stack-list-frames} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-stack-list-locals} Command
@findex -stack-list-locals
@anchor{-stack-list-locals}
+@subheading The @code{-stack-list-locals} Command
@subsubheading Synopsis
@end smallexample
@anchor{-stack-list-variables}
-@subheading The @code{-stack-list-variables} Command
@findex -stack-list-variables
+@subheading The @code{-stack-list-variables} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-stack-select-frame} Command
@findex -stack-select-frame
+@subheading The @code{-stack-select-frame} Command
@subsubheading Synopsis
@subheading Description And Use of Operations on Variable Objects
-@subheading The @code{-enable-pretty-printing} Command
@findex -enable-pretty-printing
+@subheading The @code{-enable-pretty-printing} Command
@smallexample
-enable-pretty-printing
Note that if Python support has not been compiled into @value{GDBN},
this command will still succeed (and do nothing).
-This feature is currently (as of @value{GDBN} 7.0) experimental, and
-may work differently in future versions of @value{GDBN}.
-
-@subheading The @code{-var-create} Command
@findex -var-create
+@subheading The @code{-var-create} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-var-delete} Command
@findex -var-delete
+@subheading The @code{-var-delete} Command
@subsubheading Synopsis
Returns an error if the object @var{name} is not found.
-@subheading The @code{-var-set-format} Command
@findex -var-set-format
+@subheading The @code{-var-set-format} Command
@subsubheading Synopsis
For a variable with children, the format is set only on the
variable itself, and the children are not affected.
-@subheading The @code{-var-show-format} Command
@findex -var-show-format
+@subheading The @code{-var-show-format} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-var-info-num-children} Command
@findex -var-info-num-children
+@subheading The @code{-var-info-num-children} Command
@subsubheading Synopsis
be available.
-@subheading The @code{-var-list-children} Command
@findex -var-list-children
+@subheading The @code{-var-list-children} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-var-info-type} Command
@findex -var-info-type
+@subheading The @code{-var-info-type} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-var-info-expression} Command
@findex -var-info-expression
+@subheading The @code{-var-info-expression} Command
@subsubheading Synopsis
includes those expressions, so the @code{-var-info-expression} command
is of limited use.
-@subheading The @code{-var-info-path-expression} Command
@findex -var-info-path-expression
+@subheading The @code{-var-info-path-expression} Command
@subsubheading Synopsis
^done,path_expr=((Base)c).m_size)
@end smallexample
-@subheading The @code{-var-show-attributes} Command
@findex -var-show-attributes
+@subheading The @code{-var-show-attributes} Command
@subsubheading Synopsis
@noindent
where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
-@subheading The @code{-var-evaluate-expression} Command
@findex -var-evaluate-expression
+@subheading The @code{-var-evaluate-expression} Command
@subsubheading Synopsis
Note that one must invoke @code{-var-list-children} for a variable
before the value of a child variable can be evaluated.
-@subheading The @code{-var-assign} Command
@findex -var-assign
+@subheading The @code{-var-assign} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-var-update} Command
@findex -var-update
+@subheading The @code{-var-update} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-var-set-frozen} Command
@findex -var-set-frozen
@anchor{-var-set-frozen}
+@subheading The @code{-var-set-frozen} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-var-set-update-range} command
@findex -var-set-update-range
@anchor{-var-set-update-range}
+@subheading The @code{-var-set-update-range} command
@subsubheading Synopsis
^done
@end smallexample
-@subheading The @code{-var-set-visualizer} command
@findex -var-set-visualizer
@anchor{-var-set-visualizer}
+@subheading The @code{-var-set-visualizer} command
@subsubheading Synopsis
@c @subsubheading Example
@c N.A.
-@subheading The @code{-data-disassemble} Command
@findex -data-disassemble
+@subheading The @code{-data-disassemble} Command
@subsubheading Synopsis
@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}
+ ( -s @var{start-addr} -e @var{end-addr}
+ | -a @var{addr}
+ | -f @var{filename} -l @var{linenum} [ -n @var{lines} ] )
+ [ --opcodes @var{opcodes-mode} ]
+ [ --source ]
+ [ -- @var{mode} ]
@end smallexample
@noindent
displayed; if @var{lines} is higher than the number of lines between
@var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
are displayed.
+@item @var{opcodes-mode}
+can only be used with @var{mode} 0, and should be one of the following:
+@table @samp
+@item none
+no opcode information will be included in the result.
+
+@item bytes
+opcodes will be included in the result, the opcodes will be formatted
+as for @kbd{disassemble /b}.
+
+@item display
+opcodes will be included in the result, the opcodes will be formatted
+as for @kbd{disassemble /r}.
+@end table
@item @var{mode}
-is one of:
-@itemize @bullet
-@item 0 disassembly only
-@item 1 mixed source and disassembly (deprecated)
-@item 2 disassembly with raw opcodes
-@item 3 mixed source and disassembly with raw opcodes (deprecated)
-@item 4 mixed source and disassembly
-@item 5 mixed source and disassembly with raw opcodes
-@end itemize
+the use of @var{mode} is deprecated in favour of using the
+@code{--opcodes} and @code{--source} options. When no @var{mode} is
+given, @var{mode} 0 will be assumed. However, the @var{mode} is still
+available for backward compatibility. The @var{mode} should be one of:
+@table @samp
+@item 0
+@emph{disassembly only}, this is the default mode if no mode is
+specified.
+
+@item 1
+@emph{mixed source and disassembly (deprecated)}, it is not possible
+to recreate this mode using @code{--opcodes} and @code{--source}
+options.
+
+@item 2
+@emph{disassembly with raw opcodes}, this mode is equivalent to using
+@var{mode} 0 and passing @code{--opcodes bytes} to the command.
+
+@item 3
+@emph{mixed source and disassembly with raw opcodes (deprecated)}, it
+is not possible to recreate this mode using @code{--opcodes} and
+@code{--source} options.
+
+@item 4
+@emph{mixed source and disassembly}, this mode is equivalent to using
+@var{mode} 0 and passing @code{--source} to the command.
+@item 5
+@emph{mixed source and disassembly with raw opcodes}, this mode is
+equivalent to using @var{mode} 0 and passing @code{--opcodes bytes}
+and @code{--source} to the command.
+@end table
Modes 1 and 3 are deprecated. The output is ``source centric''
which hasn't proved useful in practice.
@xref{Machine Code}, for a discussion of the difference between
@code{/m} and @code{/s} output of the @code{disassemble} command.
@end table
+The @code{--source} can only be used with @var{mode} 0. Passing this
+option will include the source code in the disassembly result as if
+@var{mode} 4 or 5 had been used.
+
@subsubheading Result
The result of the @code{-data-disassemble} command will be a list named
-@samp{asm_insns}, the contents of this list depend on the @var{mode}
-used with the @code{-data-disassemble} command.
+@samp{asm_insns}, the contents of this list depend on the options used
+with the @code{-data-disassemble} command.
-For modes 0 and 2 the @samp{asm_insns} list contains tuples with the
-following fields:
+For modes 0 and 2, and when the @code{--source} option is not used, the
+@samp{asm_insns} list contains tuples with the following fields:
@table @code
@item address
The text disassembly for this @samp{address}.
@item opcodes
-This field is only present for modes 2, 3 and 5. This contains the raw opcode
-bytes for the @samp{inst} field.
+This field is only present for modes 2, 3 and 5, or when the
+@code{--opcodes} option @samp{bytes} or @samp{display} is used. This
+contains the raw opcode bytes for the @samp{inst} field.
+
+When the @samp{--opcodes} option is not passed to
+@code{-data-disassemble}, or the @samp{bytes} value is passed to
+@samp{--opcodes}, then the bytes are formatted as a series of single
+bytes, in hex, in ascending address order, with a single space between
+each byte. This format is equivalent to the @samp{/b} option being
+used with the @kbd{disassemble} command
+(@pxref{disassemble,,@kbd{disassemble}}).
+When @samp{--opcodes} is passed the value @samp{display} then the bytes
+are formatted in the natural instruction display order. This means
+multiple bytes can be grouped together, and the bytes might be
+byte-swapped. This format is equivalent to the @samp{/r} option being
+used with the @kbd{disassemble} command.
@end table
-For modes 1, 3, 4 and 5 the @samp{asm_insns} list contains tuples named
-@samp{src_and_asm_line}, each of which has the following fields:
+For modes 1, 3, 4 and 5, or when the @code{--source} option is used, the
+@samp{asm_insns} list contains tuples named @samp{src_and_asm_line},
+each of which has the following fields:
@table @code
@item line
@end smallexample
-@subheading The @code{-data-evaluate-expression} Command
@findex -data-evaluate-expression
+@subheading The @code{-data-evaluate-expression} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-data-list-changed-registers} Command
@findex -data-list-changed-registers
+@subheading The @code{-data-list-changed-registers} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-data-list-register-names} Command
@findex -data-list-register-names
+@subheading The @code{-data-list-register-names} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-data-list-register-values} Command
@findex -data-list-register-values
+@subheading The @code{-data-list-register-values} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-data-read-memory} Command
@findex -data-read-memory
+@subheading The @code{-data-read-memory} Command
This command is deprecated, use @code{-data-read-memory-bytes} instead.
(gdb)
@end smallexample
-@subheading The @code{-data-read-memory-bytes} Command
@findex -data-read-memory-bytes
+@subheading The @code{-data-read-memory-bytes} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-data-write-memory-bytes} Command
@findex -data-write-memory-bytes
+@subheading The @code{-data-write-memory-bytes} Command
@subsubheading Synopsis
The commands defined in this section implement MI support for
tracepoints. For detailed introduction, see @ref{Tracepoints}.
-@subheading The @code{-trace-find} Command
@findex -trace-find
+@subheading The @code{-trace-find} Command
@subsubheading Synopsis
the specified range. Both bounds are considered to be inside the range.
@item line
-Line specification is required as parameter. @xref{Specify Location}.
+Location specification is required as parameter. @xref{Location Specifications}.
Finds next trace frame that corresponds to a tracepoint at
the specified location.
The corresponding @value{GDBN} command is @samp{tfind}.
-@subheading -trace-define-variable
@findex -trace-define-variable
+@subheading -trace-define-variable
@subsubheading Synopsis
The corresponding @value{GDBN} command is @samp{tvariable}.
-@subheading The @code{-trace-frame-collected} Command
@findex -trace-frame-collected
+@subheading The @code{-trace-frame-collected} Command
@subsubheading Synopsis
@subsubheading Example
-@subheading -trace-list-variables
@findex -trace-list-variables
+@subheading -trace-list-variables
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading -trace-save
@findex -trace-save
+@subheading -trace-save
@subsubheading Synopsis
The corresponding @value{GDBN} command is @samp{tsave}.
-@subheading -trace-start
@findex -trace-start
+@subheading -trace-start
@subsubheading Synopsis
The corresponding @value{GDBN} command is @samp{tstart}.
-@subheading -trace-status
@findex -trace-status
+@subheading -trace-status
@subsubheading Synopsis
The corresponding @value{GDBN} command is @samp{tstatus}.
-@subheading -trace-stop
@findex -trace-stop
+@subheading -trace-stop
@subsubheading Synopsis
@ignore
-@subheading The @code{-symbol-info-address} Command
@findex -symbol-info-address
+@subheading The @code{-symbol-info-address} Command
@subsubheading Synopsis
N.A.
-@subheading The @code{-symbol-info-file} Command
@findex -symbol-info-file
+@subheading The @code{-symbol-info-file} Command
@subsubheading Synopsis
N.A.
@end ignore
-@subheading The @code{-symbol-info-functions} Command
@findex -symbol-info-functions
@anchor{-symbol-info-functions}
+@subheading The @code{-symbol-info-functions} Command
@subsubheading Synopsis
@end group
@end smallexample
-@subheading The @code{-symbol-info-module-functions} Command
@findex -symbol-info-module-functions
@anchor{-symbol-info-module-functions}
+@subheading The @code{-symbol-info-module-functions} Command
@subsubheading Synopsis
@end group
@end smallexample
-@subheading The @code{-symbol-info-module-variables} Command
@findex -symbol-info-module-variables
@anchor{-symbol-info-module-variables}
+@subheading The @code{-symbol-info-module-variables} Command
@subsubheading Synopsis
@end group
@end smallexample
-@subheading The @code{-symbol-info-modules} Command
@findex -symbol-info-modules
@anchor{-symbol-info-modules}
+@subheading The @code{-symbol-info-modules} Command
@subsubheading Synopsis
@end group
@end smallexample
-@subheading The @code{-symbol-info-types} Command
@findex -symbol-info-types
@anchor{-symbol-info-types}
+@subheading The @code{-symbol-info-types} Command
@subsubheading Synopsis
@end group
@end smallexample
-@subheading The @code{-symbol-info-variables} Command
@findex -symbol-info-variables
@anchor{-symbol-info-variables}
+@subheading The @code{-symbol-info-variables} Command
@subsubheading Synopsis
@end smallexample
@ignore
-@subheading The @code{-symbol-info-line} Command
@findex -symbol-info-line
+@subheading The @code{-symbol-info-line} Command
@subsubheading Synopsis
N.A.
-@subheading The @code{-symbol-info-symbol} Command
@findex -symbol-info-symbol
+@subheading The @code{-symbol-info-symbol} Command
@subsubheading Synopsis
N.A.
-@subheading The @code{-symbol-list-functions} Command
@findex -symbol-list-functions
+@subheading The @code{-symbol-list-functions} Command
@subsubheading Synopsis
@end ignore
-@subheading The @code{-symbol-list-lines} Command
@findex -symbol-list-lines
+@subheading The @code{-symbol-list-lines} Command
@subsubheading Synopsis
@ignore
-@subheading The @code{-symbol-list-types} Command
@findex -symbol-list-types
+@subheading The @code{-symbol-list-types} Command
@subsubheading Synopsis
N.A.
-@subheading The @code{-symbol-list-variables} Command
@findex -symbol-list-variables
+@subheading The @code{-symbol-list-variables} Command
@subsubheading Synopsis
N.A.
-@subheading The @code{-symbol-locate} Command
@findex -symbol-locate
+@subheading The @code{-symbol-locate} Command
@subsubheading Synopsis
N.A.
-@subheading The @code{-symbol-type} Command
@findex -symbol-type
+@subheading The @code{-symbol-type} Command
@subsubheading Synopsis
This section describes the GDB/MI commands to specify executable file names
and to read in and obtain symbol table information.
-@subheading The @code{-file-exec-and-symbols} Command
@findex -file-exec-and-symbols
+@subheading The @code{-file-exec-and-symbols} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-file-exec-file} Command
@findex -file-exec-file
+@subheading The @code{-file-exec-file} Command
@subsubheading Synopsis
@ignore
-@subheading The @code{-file-list-exec-sections} Command
@findex -file-list-exec-sections
+@subheading The @code{-file-list-exec-sections} Command
@subsubheading Synopsis
@end ignore
-@subheading The @code{-file-list-exec-source-file} Command
@findex -file-list-exec-source-file
+@subheading The @code{-file-list-exec-source-file} Command
@subsubheading Synopsis
@end smallexample
+@findex -file-list-exec-source-files
@subheading The @code{-file-list-exec-source-files} Command
@kindex info sources
-@findex -file-list-exec-source-files
@subsubheading Synopsis
sources=[]@}]
@end smallexample
-@subheading The @code{-file-list-shared-libraries} Command
@findex -file-list-shared-libraries
+@subheading The @code{-file-list-shared-libraries} Command
@subsubheading Synopsis
@ignore
-@subheading The @code{-file-list-symbol-files} Command
@findex -file-list-symbol-files
+@subheading The @code{-file-list-symbol-files} Command
@subsubheading Synopsis
@end ignore
-@subheading The @code{-file-symbol-file} Command
@findex -file-symbol-file
+@subheading The @code{-file-symbol-file} Command
@subsubheading Synopsis
@section @sc{gdb/mi} Target Manipulation Commands
-@subheading The @code{-target-attach} Command
@findex -target-attach
+@subheading The @code{-target-attach} Command
@subsubheading Synopsis
@end smallexample
@ignore
-@subheading The @code{-target-compare-sections} Command
@findex -target-compare-sections
+@subheading The @code{-target-compare-sections} Command
@subsubheading Synopsis
@end ignore
-@subheading The @code{-target-detach} Command
@findex -target-detach
+@subheading The @code{-target-detach} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-target-disconnect} Command
@findex -target-disconnect
+@subheading The @code{-target-disconnect} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-target-download} Command
@findex -target-download
+@subheading The @code{-target-download} Command
@subsubheading Synopsis
@ignore
-@subheading The @code{-target-exec-status} Command
@findex -target-exec-status
+@subheading The @code{-target-exec-status} Command
@subsubheading Synopsis
N.A.
-@subheading The @code{-target-list-available-targets} Command
@findex -target-list-available-targets
+@subheading The @code{-target-list-available-targets} Command
@subsubheading Synopsis
N.A.
-@subheading The @code{-target-list-current-targets} Command
@findex -target-list-current-targets
+@subheading The @code{-target-list-current-targets} Command
@subsubheading Synopsis
N.A.
-@subheading The @code{-target-list-parameters} Command
@findex -target-list-parameters
+@subheading The @code{-target-list-parameters} Command
@subsubheading Synopsis
@subsubheading Example
N.A.
-@subheading The @code{-target-flash-erase} Command
@findex -target-flash-erase
+@subheading The @code{-target-flash-erase} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-target-select} Command
@findex -target-select
+@subheading The @code{-target-select} Command
@subsubheading Synopsis
@section @sc{gdb/mi} File Transfer Commands
-@subheading The @code{-target-file-put} Command
@findex -target-file-put
+@subheading The @code{-target-file-put} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-target-file-get} Command
@findex -target-file-get
+@subheading The @code{-target-file-get} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-target-file-delete} Command
@findex -target-file-delete
+@subheading The @code{-target-file-delete} Command
@subsubheading Synopsis
@node GDB/MI Ada Exceptions Commands
@section Ada Exceptions @sc{gdb/mi} Commands
-@subheading The @code{-info-ada-exceptions} Command
@findex -info-ada-exceptions
+@subheading The @code{-info-ada-exceptions} Command
@subsubheading Synopsis
about support for these capabilities. Similarly, it is also possible
to query @value{GDBN} about target support of certain features.
-@subheading The @code{-info-gdb-mi-command} Command
@cindex @code{-info-gdb-mi-command}
@findex -info-gdb-mi-command
+@subheading The @code{-info-gdb-mi-command} Command
@subsubheading Synopsis
^done,command=@{exists="true"@}
@end smallexample
-@subheading The @code{-list-features} Command
@findex -list-features
@cindex supported @sc{gdb/mi} features, list
+@subheading The @code{-list-features} Command
Returns a list of particular features of the MI protocol that
this version of gdb implements. A feature can be a command,
option (@pxref{GDB/MI Data Manipulation}).
@end ftable
-@subheading The @code{-list-target-features} Command
@findex -list-target-features
+@subheading The @code{-list-target-features} Command
Returns a list of particular features that are supported by the
target. Those features affect the permitted MI commands, but
@c @subheading -gdb-complete
-@subheading The @code{-gdb-exit} Command
@findex -gdb-exit
+@subheading The @code{-gdb-exit} Command
@subsubheading Synopsis
@ignore
-@subheading The @code{-exec-abort} Command
@findex -exec-abort
+@subheading The @code{-exec-abort} Command
@subsubheading Synopsis
@end ignore
-@subheading The @code{-gdb-set} Command
@findex -gdb-set
+@subheading The @code{-gdb-set} Command
@subsubheading Synopsis
@end smallexample
-@subheading The @code{-gdb-show} Command
@findex -gdb-show
+@subheading The @code{-gdb-show} Command
@subsubheading Synopsis
@c @subheading -gdb-source
-@subheading The @code{-gdb-version} Command
@findex -gdb-version
+@subheading The @code{-gdb-version} Command
@subsubheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-list-thread-groups} Command
@findex -list-thread-groups
+@subheading The @code{-list-thread-groups} Command
@subheading Synopsis
@{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},...]
@end smallexample
-@subheading The @code{-info-os} Command
@findex -info-os
+@subheading The @code{-info-os} Command
@subsubheading Synopsis
popup menu, but is needless clutter on the command line, and
@code{info os} omits it.)
-@subheading The @code{-add-inferior} Command
@findex -add-inferior
+@subheading The @code{-add-inferior} Command
@subheading Synopsis
^done,inferior="i3"
@end smallexample
-@subheading The @code{-interpreter-exec} Command
+@findex -remove-inferior
+@subheading The @code{-remove-inferior} Command
+
+@subsubheading Synopsis
+
+@smallexample
+-remove-inferior @var{inferior-id}
+@end smallexample
+
+Removes an inferior (@pxref{Inferiors Connections and Programs}).
+Only inferiors that have exited can be removed. The @var{inferior-id}
+is the inferior to be removed, and should be the same id string as
+returned by the @samp{-add-inferior} command.
+
+When an inferior is successfully removed a
+@code{=thread-group-removed} notification (@pxref{GDB/MI Async
+Records}) is emitted, the @var{id} field of which contains the
+@var{inferior-id} for the removed inferior.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{remove-inferiors}
+(@pxref{remove_inferiors_cli,,@samp{remove-inferiors}}).
+
+@subsubheading Example
+
+@smallexample
+(@value{GDBP})
+-remove-inferior i3
+=thread-group-removed,id="i3"
+^done
+@end smallexample
+
@findex -interpreter-exec
+@subheading The @code{-interpreter-exec} Command
@subheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-inferior-tty-set} Command
@findex -inferior-tty-set
+@subheading The @code{-inferior-tty-set} Command
@subheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-inferior-tty-show} Command
@findex -inferior-tty-show
+@subheading The @code{-inferior-tty-show} Command
@subheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-enable-timings} Command
@findex -enable-timings
+@subheading The @code{-enable-timings} Command
@subheading Synopsis
(gdb)
@end smallexample
-@subheading The @code{-complete} Command
@findex -complete
+@subheading The @code{-complete} Command
@subheading Synopsis
This library may be included with your operating system distribution;
if it is not, you can get the latest version from
@url{https://gmplib.org/}. If GMP is installed at an unusual path,
-you can use the @option{--with-libgmp-prefix} option to specify
+you can use the @option{--with-gmp} option or options
+@option{--with-gmp-include} and @option{--with-gmp-lib} to specify
its location.
@end table
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.
+@option{--with-liblzma-prefix} option to specify its location.
@item MPFR
@anchor{MPFR}
-@value{GDBN} can use the GNU MPFR multiple-precision floating-point
+@value{GDBN} now uses 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.
+in an unusual path, you can use the @option{--with-mpfr} option or options
+@option{--with-mpfr-include} and @option{--with-mpfr-lib} 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.
+formats than the host.
@item Python
@value{GDBN} can be scripted using Python language. @xref{Python}.
@table @code
@kindex maint agent
@kindex maint agent-eval
-@item maint agent @r{[}-at @var{location}@r{,}@r{]} @var{expression}
-@itemx maint agent-eval @r{[}-at @var{location}@r{,}@r{]} @var{expression}
+@item maint agent @r{[}-at @var{linespec}@r{,}@r{]} @var{expression}
+@itemx maint agent-eval @r{[}-at @var{linespec}@r{,}@r{]} @var{expression}
Translate the given @var{expression} into remote agent bytecodes.
This command is useful for debugging the Agent Expression mechanism
(@pxref{Agent Expressions}). The @samp{agent} version produces an
of the addresses of @code{globa} and @code{globb}, while discarding
the result of the addition, while an evaluation expression will do the
addition and return the sum.
-If @code{-at} is given, generate remote agent bytecode for @var{location}.
+If @code{-at} is given, generate remote agent bytecode for all the
+addresses to which @var{linespec} resolves (@pxref{Linespec
+Locations}).
If not, generate remote agent bytecode for current frame PC address.
@kindex maint agent-printf
@item maint info jit
Print information about JIT code objects loaded in the current inferior.
+@anchor{maint info python-disassemblers}
+@kindex maint info python-disassemblers
+@item maint info python-disassemblers
+This command is defined within the @code{gdb.disassembler} Python
+module (@pxref{Disassembly In Python}), and will only be present after
+that module has been imported. To force the module to be imported do
+the following:
+
+@smallexample
+(@value{GDBP}) python import gdb.disassembler
+@end smallexample
+
+This command lists all the architectures for which a disassembler is
+currently registered, and the name of the disassembler. If a
+disassembler is registered for all architectures, then this is listed
+last against the @samp{GLOBAL} architecture.
+
+If one of the disassemblers would be selected for the architecture of
+the current inferior, then this disassembler will be marked.
+
+The following example shows a situation in which two disassemblers are
+registered, initially the @samp{i386} disassembler matches the current
+architecture, then the architecture is changed, now the @samp{GLOBAL}
+disassembler matches.
+
+@smallexample
+@group
+(@value{GDBP}) show architecture
+The target architecture is set to "auto" (currently "i386").
+(@value{GDBP}) maint info python-disassemblers
+Architecture Disassember Name
+i386 Disassembler_1 (Matches current architecture)
+GLOBAL Disassembler_2
+@end group
+@group
+(@value{GDBP}) set architecture arm
+The target architecture is set to "arm".
+(@value{GDBP}) maint info python-disassemblers
+quit
+Architecture Disassember Name
+i386 Disassembler_1
+GLOBAL Disassembler_2 (Matches current architecture)
+@end group
+@end smallexample
+
@kindex set displaced-stepping
@kindex show displaced-stepping
@cindex displaced stepping support
Takes an optional file parameter.
+@kindex maint print frame-id
+@item maint print frame-id
+@itemx maint print frame-id @var{level}
+Print @value{GDBN}'s internal frame-id for the frame at relative
+@var{level}, or for the currently selected frame when @var{level} is
+not given.
+
+If used, @var{level} should be an integer, as displayed in the
+@command{backtrace} output.
+
+@smallexample
+(@value{GDBP}) maint print frame-id
+frame-id for frame #0: @{stack=0x7fffffffac70,code=0x0000000000401106,!special@}
+(@value{GDBP}) maint print frame-id 2
+frame-id for frame #2: @{stack=0x7fffffffac90,code=0x000000000040111c,!special@}
+@end smallexample
+
@kindex maint print registers
@kindex maint print raw-registers
@kindex maint print cooked-registers
a recursive definition of the data type as stored in @value{GDBN}'s
data structures, including its flags and contained types.
+@kindex maint print record-instruction
+@item maint print record-instruction
+@itemx maint print record-instruction @var{N}
+print how GDB recorded a given instruction. If @var{n} is not positive
+number, it prints the values stored by the inferior before the @var{n}-th previous
+instruction was exectued. If @var{n} is positive, print the values after the @var{n}-th
+following instruction is executed. If @var{n} is not given, 0 is assumed.
+
@kindex maint selftest
@cindex self tests
@item maint selftest @r{[}-verbose@r{]} @r{[}@var{filter}@r{]}
Here is an example of the resulting disassembly:
@smallexample
-(gdb) info addr argc
+(@value{GDBP}) info addr argc
Symbol "argc" is a complex DWARF expression:
1: DW_OP_fbreg 0
@end smallexample
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 info frame-unwinders
+@item maint info frame-unwinders
+List the frame unwinders currently in effect, starting with the highest priority.
+
@kindex maint set worker-threads
@kindex maint show worker-threads
@item maint set worker-threads
library when @value{GDBN} is linked against the GNU Source Highlight
library.
+@anchor{maint_libopcodes_styling}
+@kindex maint set libopcodes-styling enabled
+@kindex maint show libopcodes-styling enabled
+@item maint set libopcodes-styling enabled @r{[}on|off@r{]}
+@itemx maint show libopcodes-styling enabled
+Control whether @value{GDBN} should use its builtin disassembler
+(@file{libopcodes}) to style disassembler output (@pxref{Output
+Styling}). The builtin disassembler does not support styling for all
+architectures.
+
+When this option is @samp{off} the builtin disassembler will not be
+used for styling, @value{GDBN} will fall back to using the Python
+Pygments package if possible.
+
+Trying to set this option @samp{on} for an architecture that the
+builtin disassembler is unable to style will give an error, otherwise,
+the builtin disassembler will be used to style disassembler output.
+
+This option is @samp{on} by default for supported architectures.
+
+This option is useful for debugging @value{GDBN}'s use of the Pygments
+library when @value{GDBN} is built for an architecture that supports
+styling with the builtin disassembler
@kindex maint space
@cindex memory used by commands
@item maint space @var{value}
variables. This is used by the testsuite to exercise the @code{with}
command's infrastructure.
+@kindex maint ignore-probes
+@item maint ignore-probes [@var{-v}|@var{-verbose}] [@var{provider} [@var{name} [@var{objfile}]]]
+@itemx maint ignore-probes @var{-reset}
+Set or reset the ignore-probes filter. The @var{provider}, @var{name}
+and @var{objfile} arguments are as in @code{enable probes} and
+@code{disable probes} (@pxref{enable probes}). Only supported for
+SystemTap probes.
+
+Here's an example of using @code{maint ignore-probes}:
+@smallexample
+(gdb) maint ignore-probes -verbose libc ^longjmp$
+ignore-probes filter has been set to:
+PROVIDER: 'libc'
+PROBE_NAME: '^longjmp$'
+OBJNAME: ''
+(gdb) start
+<... more output ...>
+Ignoring SystemTap probe libc longjmp in /lib64/libc.so.6.^M
+Ignoring SystemTap probe libc longjmp in /lib64/libc.so.6.^M
+Ignoring SystemTap probe libc longjmp in /lib64/libc.so.6.^M
+@end smallexample
@end table
The following command is useful for non-interactive invocations of
Each byte of register data is described by two hex digits. The bytes
with the register are transmitted in target byte order. The size of
each register and their position within the @samp{g} packet are
-determined by the @value{GDBN} internal gdbarch functions
-@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{gdbarch_register_name}.
-
-When reading registers from a trace frame (@pxref{Analyze Collected
-Data,,Using the Collected Data}), the stub may also return a string of
-literal @samp{x}'s in place of the register data digits, to indicate
-that the corresponding register has not been collected, thus its value
-is unavailable. For example, for an architecture with 4 registers of
+determined by the target description (@pxref{Target Descriptions}); in
+the absence of a target description, this is done using code internal
+to @value{GDBN}; typically this is some customary register layout for
+the architecture in question.
+
+When reading registers, the stub may also return a string of literal
+@samp{x}'s in place of the register data digits, to indicate that the
+corresponding register's value is unavailable. For example, when
+reading registers from a trace frame (@pxref{Analyze Collected
+Data,,Using the Collected Data}), this means that the register has not
+been collected in the trace frame. When reading registers from a live
+program, this indicates that the stub has no means to access the
+register contents, even though the corresponding register is known to
+exist. Note that if a register truly does not exist on the target,
+then it is better to not include it in the target description in the
+first place.
+
+For example, for an architecture with 4 registers of
4 bytes each, the following reply indicates to @value{GDBN} that
-registers 0 and 2 have not been collected, while registers 1 and 3
-have been collected, and both have zero value:
+registers 0 and 2 are unavailable, while registers 1 and 3
+are available, and both have zero value:
@smallexample
-> @code{g}
two-digit hex number.
@item
-If @var{n} is @samp{thread}, then @var{r} is the @var{thread-id} of
+If @var{n} is @samp{thread}, then @var{r} is the thread ID of
the stopped thread, as specified in @ref{thread-id syntax}.
@item
@cindex fork events, remote reply
@item fork
-The packet indicates that @code{fork} was called, and @var{r}
-is the thread ID of the new child process. Refer to
-@ref{thread-id syntax} for the format of the @var{thread-id}
-field. This packet is only applicable to targets that support
-fork events.
+The packet indicates that @code{fork} was called, and @var{r} is the
+thread ID of the new child process, as specified in @ref{thread-id
+syntax}. This packet is only applicable to targets that support fork
+events.
This packet should not be sent by default; older @value{GDBN} versions
did not support it. @value{GDBN} requests it, by supplying an
@cindex vfork events, remote reply
@item vfork
-The packet indicates that @code{vfork} was called, and @var{r}
-is the thread ID of the new child process. Refer to
-@ref{thread-id syntax} for the format of the @var{thread-id}
-field. This packet is only applicable to targets that support
-vfork events.
+The packet indicates that @code{vfork} was called, and @var{r} is the
+thread ID of the new child process, as specified in @ref{thread-id
+syntax}. This packet is only applicable to targets that support vfork
+events.
This packet should not be sent by default; older @value{GDBN} versions
did not support it. @value{GDBN} requests it, by supplying an
@item @var{OUTPUT}
A command response with the hex encoded output string @var{OUTPUT}.
@item E @var{NN}
-Indicate a badly formed request.
+Indicate a badly formed request. The error number @var{NN} is given as
+hex digits.
@item @w{}
An empty reply indicates that @samp{qRcmd} is not recognized.
@end table
the remote stub will expect that no @samp{struct link_map}
exists prior to the starting point.
+@item lmid=@var{lmid}
+A hexadecimal number specifying a namespace identifier. This is
+currently only used together with @samp{start} to provide the
+namespace identifier back to @value{GDBN} in the response.
+@value{GDBN} will only provide values that were previously reported to
+it. If unset, the response will include @samp{lmid="0x0"}.
@end table
Arguments that are not understood by the remote stub will be silently
address the file was prelinked to during the library load.
@item
@code{l_ld}, which is memory address of the @code{PT_DYNAMIC} segment
+@item
+@code{lmid}, which is an identifier for a linker namespace, such as
+the memory address of the @code{r_debug} object that contains this
+namespace's load map or the namespace identifier returned by
+@code{dlinfo (3)}.
@end itemize
Additionally the single @code{main-lm} attribute specifies address of
@smallexample
<library-list-svr4 version="1.0" main-lm="0xe4f8f8">
<library name="/lib/ld-linux.so.2" lm="0xe4f51c" l_addr="0xe2d000"
- l_ld="0xe4eefc"/>
+ l_ld="0xe4eefc" lmid="0xfffe0"/>
<library name="/lib/libc.so.6" lm="0xe4fbe8" l_addr="0x154000"
- l_ld="0x152350"/>
+ l_ld="0x152350" lmid="0xfffe0"/>
</library-list-svr>
@end smallexample
<!ATTLIST library lm CDATA #REQUIRED>
<!ATTLIST library l_addr CDATA #REQUIRED>
<!ATTLIST library l_ld CDATA #REQUIRED>
+<!ATTLIST library lmid CDATA #IMPLIED>
@end smallexample
@node Memory Map Format
One can fetch individual fields like in @samp{C}.
@smallexample
-(gdb) print $my_struct_reg.field3
+(@value{GDBP}) print $my_struct_reg.field3
$1 = 42
@end smallexample
would be printed as:
@smallexample
-(gdb) info register flags
+(@value{GDBP}) info register flags
flags 0x3 [ X LEVEL=high ]
@end smallexample
If this feature is present, @samp{org.gnu.gdb.arm.vfp} must also
be present and include 32 double-precision registers.
+The @samp{org.gnu.gdb.arm.m-profile-pacbti} feature is optional, and
+acknowledges support for the ARMv8.1-m PACBTI extensions. @value{GDBN}
+will track return address signing states and will decorate backtraces using
+the [PAC] marker, similar to AArch64's PAC extension.
+@xref{AArch64 PAC}.
+
@node i386 Features
@subsection i386 Features
@cindex target descriptions, i386 features
@samp{pc}, and @samp{badv}. Either the architectural names (@samp{r0},
@samp{r1}, etc) can be used, or the ABI names (@samp{zero}, @samp{ra}, etc).
+The @samp{org.gnu.gdb.loongarch.fpu} feature is optional. If present,
+it should contain registers @samp{f0} through @samp{f31}, @samp{fcc},
+and @samp{fcsr}.
+
@node MicroBlaze Features
@subsection MicroBlaze Features
@cindex target descriptions, MicroBlaze features
regarding @code{debuginfod}.
@menu
-* Debuginfod Settings:: Configuring debuginfod with @value{GDBN}
+* Debuginfod Settings:: Configuring debuginfod with @value{GDBN}
@end menu
@node Debuginfod Settings
@item --readnever
Do not read symbol files.
-@item --dbx
-Run in DBX compatibility mode.
-
@item --return-child-result
@value{GDBN}'s exit code will be the same as the child's exit code.
@smallexample
@ifset man
@c @file would wrap it as F</dev/ttyb>.
-(gdb) target remote /dev/ttyb
+(@value{GDBP}) target remote /dev/ttyb
@end ifset
@ifclear man
-(gdb) target remote @file{/dev/ttyb}
+(@value{GDBP}) target remote @file{/dev/ttyb}
@end ifclear
@end smallexample
communicates with the server via serial line @file{/dev/ttyb}, and:
@smallexample
-(gdb) target remote the-target:2345
+(@value{GDBP}) target remote the-target:2345
@end smallexample
@noindent
In such case use the @code{extended-remote} @value{GDBN} command variant:
@smallexample
-(gdb) target extended-remote the-target:2345
+(@value{GDBP}) target extended-remote the-target:2345
@end smallexample
The @command{gdbserver} option @option{--multi} may or may not be used in such
projects / binutils-gdb.git / blobdiff