\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
@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
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{locspec}
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.
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{]}
over when stepping.
@smallexample
-(gdb) skip -gfi utils/*.c
+(@value{GDBP}) skip -gfi utils/*.c
@end smallexample
@item -function @var{linespec}
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
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.
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.
@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
* 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
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
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
@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
@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
@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
@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
@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
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
* Nios II::
* Sparc64::
* S12Z::
+* AMD GPU:: @acronym{AMD GPU} architectures
@end menu
@node AArch64
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
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
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
@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:
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
(gdb)
@end smallexample
-@subheading The @code{-dprintf-insert} Command
@findex -dprintf-insert
+@subheading The @code{-dprintf-insert} Command
@subsubheading Synopsis
(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
@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
@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).
-@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
( -s @var{start-addr} -e @var{end-addr}
| -a @var{addr}
| -f @var{filename} -l @var{linenum} [ -n @var{lines} ] )
- -- @var{mode}
+ [ --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. The bytes are formatted
-as single bytes, in hex, in ascending address order, with a single
-space between each byte.
+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 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
@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}.
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
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}
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
regarding @code{debuginfod}.
@menu
-* Debuginfod Settings:: Configuring debuginfod with @value{GDBN}
+* Debuginfod Settings:: Configuring debuginfod with @value{GDBN}
@end menu
@node Debuginfod Settings
@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