inferiors}}:
@table @code
-@kindex info inferiors
+@kindex info inferiors [ @var{id}@dots{} ]
@item info inferiors
Print a list of all inferiors currently being managed by @value{GDBN}.
+By default all inferiors are printed, but the argument @var{id}@dots{}
+-- a space separated list of inferior numbers -- can be used to limit
+the display to just the requested inferiors.
@value{GDBN} displays for each inferior (in this order):
@item automatic notification of new threads
@item @samp{thread @var{thread-id}}, a command to switch among threads
@item @samp{info threads}, a command to inquire about existing threads
-@item @samp{thread apply [@var{thread-id-list}] [@var{all}] @var{args}},
+@item @samp{thread apply [@var{thread-id-list} | all] @var{args}},
a command to apply a command to a list of threads
@item thread-specific breakpoints
@item @samp{set print thread-events}, which controls printing of
@kindex thread apply
@cindex apply command to several threads
-@item thread apply [@var{thread-id-list} | all [-ascending]] @var{command}
+@item thread apply [@var{thread-id-list} | all [-ascending]] [@var{flag}]@dots{} @var{command}
The @code{thread apply} command allows you to apply the named
@var{command} to one or more threads. Specify the threads that you
want affected using the thread ID list syntax (@pxref{thread ID
@var{command}}. To apply a command to all threads in ascending order,
type @kbd{thread apply all -ascending @var{command}}.
+The @var{flag} arguments control what output to produce and how to handle
+errors raised when applying @var{command} to a thread. @var{flag}
+must start with a @code{-} directly followed by one letter in
+@code{qcs}. If several flags are provided, they must be given
+individually, such as @code{-c -q}.
+
+By default, @value{GDBN} displays some thread information before the
+output produced by @var{command}, and an error raised during the
+execution of a @var{command} will abort @code{thread apply}. The
+following flags can be used to fine-tune this behavior:
+
+@table @code
+@item -c
+The flag @code{-c}, which stands for @samp{continue}, causes any
+errors in @var{command} to be displayed, and the execution of
+@code{thread apply} then continues.
+@item -s
+The flag @code{-s}, which stands for @samp{silent}, causes any errors
+or empty output produced by a @var{command} to be silently ignored.
+That is, the execution continues, but the thread information and errors
+are not printed.
+@item -q
+The flag @code{-q} (@samp{quiet}) disables printing the thread
+information.
+@end table
+
+Flags @code{-c} and @code{-s} cannot be used together.
+
+@kindex taas
+@cindex apply command to all threads (ignoring errors and empty output)
+@item taas @var{command}
+Shortcut for @code{thread apply all -s @var{command}}.
+Applies @var{command} on all threads, ignoring errors and empty output.
+
+@kindex tfaas
+@cindex apply a command to all frames of all threads (ignoring errors and empty output)
+@item tfaas @var{command}
+Shortcut for @code{thread apply all -s frame apply all -s @var{command}}.
+Applies @var{command} on all frames of all threads, ignoring errors
+and empty output. Note that the flag @code{-s} is specified twice:
+The first @code{-s} ensures that @code{thread apply} only shows the thread
+information of the threads for which @code{frame apply} produces
+some output. The second @code{-s} is needed to ensure that @code{frame
+apply} shows the frame information of a frame only if the
+@var{command} successfully produced some output.
+
+It can for example be used to print a local variable or a function
+argument without knowing the thread or frame where this variable or argument
+is, using:
+@smallexample
+(@value{GDBP}) tfaas p some_local_var_i_do_not_remember_where_it_is
+@end smallexample
+
@kindex thread name
@cindex name a thread
If the target doesn't support async mode, @value{GDBN} issues an error
message if you attempt to use the background execution commands.
+@cindex @code{&}, background execution of commands
To specify background execution, add a @code{&} to the command. For example,
the background form of the @code{continue} command is @code{continue&}, or
just @code{c&}. The execution commands that accept background execution
to the live target and not necessarily to the current replay
position.
+@item set record btrace cpu @var{identifier}
+Set the processor to be used for enabling workarounds for processor
+errata when decoding the trace.
+
+Processor errata are defects in processor operation, caused by its
+design or manufacture. They can cause a trace not to match the
+specification. This, in turn, may cause trace decode to fail.
+@value{GDBN} can detect erroneous trace packets and correct them, thus
+avoiding the decoding failures. These corrections are known as
+@dfn{errata workarounds}, and are enabled based on the processor on
+which the trace was recorded.
+
+By default, @value{GDBN} attempts to detect the processor
+automatically, and apply the necessary workarounds for it. However,
+you may need to specify the processor if @value{GDBN} does not yet
+support it. This command allows you to do that, and also allows to
+disable the workarounds.
+
+The argument @var{identifier} identifies the @sc{cpu} and is of the
+form: @code{@var{vendor}:@var{procesor identifier}}. In addition,
+there are two special identifiers, @code{none} and @code{auto}
+(default).
+
+The following vendor identifiers and corresponding processor
+identifiers are currently supported:
+
+@multitable @columnfractions .1 .9
+
+@item @code{intel}
+@tab @var{family}/@var{model}[/@var{stepping}]
+
+@end multitable
+
+On GNU/Linux systems, the processor @var{family}, @var{model}, and
+@var{stepping} can be obtained from @code{/proc/cpuinfo}.
+
+If @var{identifier} is @code{auto}, enable errata workarounds for the
+processor on which the trace was recorded. If @var{identifier} is
+@code{none}, errata workarounds are disabled.
+
+For example, when using an old @value{GDBN} on a new system, decode
+may fail because @value{GDBN} does not support the new processor. It
+often suffices to specify an older processor that @value{GDBN}
+supports.
+
+@smallexample
+(gdb) info record
+Active record target: record-btrace
+Recording format: Intel Processor Trace.
+Buffer size: 16kB.
+Failed to configure the Intel Processor Trace decoder: unknown cpu.
+(gdb) set record btrace cpu intel:6/158
+(gdb) info record
+Active record target: record-btrace
+Recording format: Intel Processor Trace.
+Buffer size: 16kB.
+Recorded 84872 instructions in 3189 functions (0 gaps) for thread 1 (...).
+@end smallexample
+
@kindex show record btrace
@item show record btrace replay-memory-access
Show the current setting of @code{replay-memory-access}.
+@item show record btrace cpu
+Show the processor to be used for enabling trace decode errata
+workarounds.
+
@kindex set record btrace bts
@item set record btrace bts buffer-size @var{size}
@itemx set record btrace bts buffer-size unlimited
* Backtrace:: Backtraces
* Selection:: Selecting a frame
* Frame Info:: Information on a frame
+* Frame Apply:: Applying a command to several frames
* Frame Filter Management:: Managing frame filters
@end menu
stack.
@anchor{backtrace-command}
-@table @code
@kindex backtrace
@kindex bt @r{(@code{backtrace})}
-@item backtrace
-@itemx bt
-Print a backtrace of the entire stack: one line per frame for all
-frames in the stack.
-
-You can stop the backtrace at any time by typing the system interrupt
-character, normally @kbd{Ctrl-c}.
-
-@item backtrace @var{n}
-@itemx bt @var{n}
-Similar, but print only the innermost @var{n} frames.
-
-@item backtrace -@var{n}
-@itemx bt -@var{n}
-Similar, but print only the outermost @var{n} frames.
-
-@item backtrace full
-@itemx bt full
-@itemx bt full @var{n}
-@itemx bt full -@var{n}
-Print the values of the local variables also. As described above,
-@var{n} specifies the number of frames to print.
-
-@item backtrace no-filters
-@itemx bt no-filters
-@itemx bt no-filters @var{n}
-@itemx bt no-filters -@var{n}
-@itemx bt no-filters full
-@itemx bt no-filters full @var{n}
-@itemx bt no-filters full -@var{n}
+To print a backtrace of the entire stack, use the @code{backtrace}
+command, or its alias @code{bt}. This command will print one line per
+frame for frames in the stack. By default, all stack frames are
+printed. You can stop the backtrace at any time by typing the system
+interrupt character, normally @kbd{Ctrl-c}.
+
+@table @code
+@item backtrace [@var{args}@dots{}]
+@itemx bt [@var{args}@dots{}]
+Print the backtrace of the entire stack. The optional @var{args} can
+be one of the following:
+
+@table @code
+@item @var{n}
+@itemx @var{n}
+Print only the innermost @var{n} frames, where @var{n} is a positive
+number.
+
+@item -@var{n}
+@itemx -@var{n}
+Print only the outermost @var{n} frames, where @var{n} is a positive
+number.
+
+@item full
+Print the values of the local variables also. This can be combined
+with a number to limit the number of frames shown.
+
+@item no-filters
Do not run Python frame filters on this backtrace. @xref{Frame
Filter API}, for more information. Additionally use @ref{disable
frame-filter all} to turn off all frame filters. This is only
relevant when @value{GDBN} has been configured with @code{Python}
support.
+
+@item hide
+A Python frame filter might decide to ``elide'' some frames. Normally
+such elided frames are still printed, but they are indented relative
+to the filtered frames that cause them to be elided. The @code{hide}
+option causes elided frames to not be printed at all.
+@end table
@end table
@kindex where
@end table
+@node Frame Apply
+@section Applying a Command to Several Frames.
+@kindex frame apply
+@cindex apply command to several frames
+@table @code
+@item frame apply [all | @var{count} | @var{-count} | level @var{level}@dots{}] [@var{flag}]@dots{} @var{command}
+The @code{frame apply} command allows you to apply the named
+@var{command} to one or more frames.
+
+@table @code
+@item @code{all}
+Specify @code{all} to apply @var{command} to all frames.
+
+@item @var{count}
+Use @var{count} to apply @var{command} to the innermost @var{count}
+frames, where @var{count} is a positive number.
+
+@item @var{-count}
+Use @var{-count} to apply @var{command} to the outermost @var{count}
+frames, where @var{count} is a positive number.
+
+@item @code{level}
+Use @code{level} to apply @var{command} to the set of frames identified
+by the @var{level} list. @var{level} is a frame level or a range of frame
+levels as @var{level1}-@var{level2}. The frame level is the number shown
+in the first field of the @samp{backtrace} command output.
+E.g., @samp{2-4 6-8 3} indicates to apply @var{command} for the frames
+at levels 2, 3, 4, 6, 7, 8, and then again on frame at level 3.
+
+@end table
+
+@end table
+
+Note that the frames on which @code{frame apply} applies a command are
+also influenced by the @code{set backtrace} settings such as @code{set
+backtrace past-main} and @code{set backtrace limit N}. See
+@xref{Backtrace,,Backtraces}.
+
+The @var{flag} arguments control what output to produce and how to handle
+errors raised when applying @var{command} to a frame. @var{flag}
+must start with a @code{-} directly followed by one letter in
+@code{qcs}. If several flags are provided, they must be given
+individually, such as @code{-c -q}.
+
+By default, @value{GDBN} displays some frame information before the
+output produced by @var{command}, and an error raised during the
+execution of a @var{command} will abort @code{frame apply}. The
+following flags can be used to fine-tune this behavior:
+
+@table @code
+@item -c
+The flag @code{-c}, which stands for @samp{continue}, causes any
+errors in @var{command} to be displayed, and the execution of
+@code{frame apply} then continues.
+@item -s
+The flag @code{-s}, which stands for @samp{silent}, causes any errors
+or empty output produced by a @var{command} to be silently ignored.
+That is, the execution continues, but the frame information and errors
+are not printed.
+@item -q
+The flag @code{-q} (@samp{quiet}) disables printing the frame
+information.
+@end table
+
+The following example shows how the flags @code{-c} and @code{-s} are
+working when applying the command @code{p j} to all frames, where
+variable @code{j} can only be successfully printed in the outermost
+@code{#1 main} frame.
+
+@smallexample
+@group
+(gdb) frame apply all p j
+#0 some_function (i=5) at fun.c:4
+No symbol "j" in current context.
+(gdb) frame apply all -c p j
+#0 some_function (i=5) at fun.c:4
+No symbol "j" in current context.
+#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11
+$1 = 5
+(gdb) frame apply all -s p j
+#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11
+$2 = 5
+(gdb)
+@end group
+@end smallexample
+
+By default, @samp{frame apply}, prints the frame location
+information before the command output:
+
+@smallexample
+@group
+(gdb) frame apply all p $sp
+#0 some_function (i=5) at fun.c:4
+$4 = (void *) 0xffffd1e0
+#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11
+$5 = (void *) 0xffffd1f0
+(gdb)
+@end group
+@end smallexample
+
+If flag @code{-q} is given, no frame information is printed:
+@smallexample
+@group
+(gdb) frame apply all -q p $sp
+$12 = (void *) 0xffffd1e0
+$13 = (void *) 0xffffd1f0
+(gdb)
+@end group
+@end smallexample
+
+@table @code
+
+@kindex faas
+@cindex apply a command to all frames (ignoring errors and empty output)
+@item faas @var{command}
+Shortcut for @code{frame apply all -s @var{command}}.
+Applies @var{command} on all frames, ignoring errors and empty output.
+
+It can for example be used to print a local variable or a function
+argument without knowing the frame where this variable or argument
+is, using:
+@smallexample
+(@value{GDBP}) faas p some_local_var_i_do_not_remember_where_it_is
+@end smallexample
+
+Note that the command @code{tfaas @var{command}} applies @var{command}
+on all frames of all threads. See @xref{Threads,,Threads}.
+@end table
+
+
@node Frame Filter Management
@section Management of Frame Filters.
@cindex managing frame filters
@table @code
@kindex info line
-@item info line @var{location}
+@item info line
+@itemx info line @var{location}
Print the starting and ending addresses of the compiled code for
source line @var{location}. You can specify source lines in any of
-the ways documented in @ref{Specify Location}.
+the ways documented in @ref{Specify Location}. With no @var{location}
+information about the current source line is printed.
@end table
For example, we can use @code{info line} to discover the location of
the object code for the first line of function
@code{m4_changequote}:
-@c FIXME: I think this example should also show the addresses in
-@c symbolic form, as they usually would be displayed.
@smallexample
(@value{GDBP}) info line m4_changequote
-Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
+Line 895 of "builtin.c" starts at pc 0x634c <m4_changequote> and \
+ ends at 0x6350 <m4_changequote+4>.
@end smallexample
@noindent
@var{location}) what source line covers a particular address:
@smallexample
(@value{GDBP}) info line *0x63ff
-Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
+Line 926 of "builtin.c" starts at pc 0x63e4 <m4_changequote+152> and \
+ ends at 0x6404 <m4_changequote+184>.
@end smallexample
@cindex @code{$_} and @code{info line}
convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience
Variables}).
+@cindex info line, repeated calls
+After @code{info line}, using @code{info line} again without
+specifying a location will display information about the next source
+line.
+
@table @code
@kindex disassemble
@cindex assembly instructions
If it is necessary to specify more than one disassembler option, then
multiple options can be placed together into a comma separated list.
-Currently this command is only supported on targets ARM, PowerPC
+Currently this command is only supported on targets ARM, MIPS, PowerPC
and S/390.
@kindex show disassembler-options
* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files
* Ravenscar Profile:: Tasking Support when using the Ravenscar
Profile
+* Ada Settings:: New settable GDB parameters for Ada.
* Ada Glitches:: Known peculiarities of Ada mode.
@end menu
@end table
+@node Ada Settings
+@subsubsection Ada Settings
+@cindex Ada settings
+
+@table @code
+@kindex set varsize-limit
+@item set varsize-limit @var{size}
+Prevent @value{GDBN} from attempting to evaluate objects whose size
+is above the given limit (@var{size}) when those sizes are computed
+from run-time quantities. This is typically the case when the object
+has a variable size, such as an array whose bounds are not known at
+compile time for example. Setting @var{size} to @code{unlimited}
+removes the size limitation. By default, the limit is about 65KB.
+
+The purpose of having such a limit is to prevent @value{GDBN} from
+trying to grab enormous chunks of virtual memory when asked to evaluate
+a quantity whose bounds have been corrupted or have not yet been fully
+initialized. The limit applies to the results of some subexpressions
+as well as to complete expressions. For example, an expression denoting
+a simple integer component, such as @code{x.y.z}, may fail if the size of
+@code{x.y} is variable and exceeds @code{size}. On the other hand,
+@value{GDBN} is sometimes clever; the expression @code{A(i)}, where
+@code{A} is an array variable with non-constant size, will generally
+succeed regardless of the bounds on @code{A}, as long as the component
+size is less than @var{size}.
+
+@kindex show varsize-limit
+@item show varsize-limit
+Show the limit on types whose size is determined by run-time quantities.
+@end table
+
@node Ada Glitches
@subsubsection Known Peculiarities of Ada Mode
@cindex Ada, problems
This command differs from @code{ptype} in two ways: first, like
@code{whatis}, it does not print a detailed description; second, it
-lists all source files where a type is defined.
+lists all source files and line numbers where a type is defined.
@kindex info type-printers
@item info type-printers
@kindex info functions
@item info functions
Print the names and data types of all defined functions.
+Similarly to @samp{info types}, this command groups its output by source
+files and annotates each function definition with its source line
+number.
@item info functions @var{regexp}
-Print the names and data types of all defined functions
-whose names contain a match for regular expression @var{regexp}.
-Thus, @samp{info fun step} finds all functions whose names
-include @code{step}; @samp{info fun ^step} finds those whose names
-start with @code{step}. If a function name contains characters
-that conflict with the regular expression language (e.g.@:
+Like @samp{info functions}, but only print the names and data types of
+functions whose names contain a match for regular expression
+@var{regexp}. Thus, @samp{info fun step} finds all functions whose
+names include @code{step}; @samp{info fun ^step} finds those whose names
+start with @code{step}. If a function name contains characters that
+conflict with the regular expression language (e.g.@:
@samp{operator*()}), they may be quoted with a backslash.
@kindex info variables
@item info variables
Print the names and data types of all variables that are defined
outside of functions (i.e.@: excluding local variables).
+The printed variables are grouped by source files and annotated with
+their respective source line numbers.
@item info variables @var{regexp}
-Print the names and data types of all variables (except for local
-variables) whose names contain a match for regular expression
+Like @kbd{info variables}, but only print the names and data types of
+non-local variables whose names contain a match for regular expression
@var{regexp}.
@kindex info classes
discard information on the executable file.
@kindex symbol-file
-@item symbol-file @r{[} @var{filename} @r{]}
+@item symbol-file @r{[} @var{filename} @r{[} -o @var{offset} @r{]]}
Read symbol table information from file @var{filename}. @code{PATH} is
searched when necessary. Use the @code{file} command to get both symbol
table and program to run from the same file.
+If an optional @var{offset} is specified, it is added to the start
+address of each section in the symbol file. This is useful if the
+program is relocated at runtime, such as the Linux kernel with kASLR
+enabled.
+
@code{symbol-file} with no argument clears out @value{GDBN} information on your
program's symbol table.
@kindex add-symbol-file
@cindex dynamic linking
-@item add-symbol-file @var{filename} @var{address}
-@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{|} -readnever @r{]}
-@itemx add-symbol-file @var{filename} @var{address} -s @var{section} @var{address} @dots{}
+@item add-symbol-file @var{filename} @r{[} -readnow @r{|} -readnever @r{]} @r{[} -o @var{offset} @r{]} @r{[} @var{textaddress} @r{]} @r{[} -s @var{section} @var{address} @dots{} @r{]}
The @code{add-symbol-file} command reads additional symbol table
information from the file @var{filename}. You would use this command
when @var{filename} has been dynamically loaded (by some other means)
-into the program that is running. The @var{address} should give the memory
-address at which the file has been loaded; @value{GDBN} cannot figure
-this out for itself. You can additionally specify an arbitrary number
-of @samp{-s @var{section} @var{address}} pairs, to give an explicit
-section name and base address for that section. You can specify any
-@var{address} as an expression.
+into the program that is running. The @var{textaddress} parameter gives
+the memory address at which the file's text section has been loaded.
+You can additionally specify the base address of other sections using
+an arbitrary number of @samp{-s @var{section} @var{address}} pairs.
+If a section is omitted, @value{GDBN} will use its default addresses
+as found in @var{filename}. Any @var{address} or @var{textaddress}
+can be given as an expression.
+
+If an optional @var{offset} is specified, it is added to the start
+address of each section, except those for which the address was
+specified explicitly.
The symbol table of the file @var{filename} is added to the symbol table
originally read with the @code{symbol-file} command. You can use the
for DWARF debugging information, not stabs. And, they do not
currently work for programs using Ada.
+@subsection Automatic symbol index cache
+
+It is possible for @value{GDBN} to automatically save a copy of this index in a
+cache on disk and retrieve it from there when loading the same binary in the
+future. This feature can be turned on with @kbd{set index-cache on}. The
+following commands can be used to tweak the behavior of the index cache.
+
+@table @code
+
+@item set index-cache on
+@itemx set index-cache off
+Enable or disable the use of the symbol index cache.
+
+@item set index-cache directory @var{directory}
+@itemx show index-cache directory
+Set/show the directory where index files will be saved. By default, the index
+is cached in the @file{gdb} subdirectory of the directory pointed to by the
+@env{XDG_CACHE_HOME} environment variable, if it is defined, else in the
+@file{.cache/gdb} subdirectory of your home directory.
+
+There is no limit on the disk space used by index cache. It is perfectly safe
+to delete the content of that directory to free up disk space.
+
+@item show index-cache stats
+Print the number of cache hits and misses since the launch of @value{GDBN}.
+
+@end table
+
@node Symbol Errors
@section Errors Reading Symbol Files
@end table
+If the @code{set endian auto} mode is in effect and no executable has
+been selected, then the endianness used is the last one chosen either
+by one of the @code{set endian big} and @code{set endian little}
+commands or by inferring from the last executable used. If no
+endianness has been previously chosen, then the default for this mode
+is inferred from the target @value{GDBN} has been built for, and is
+@code{little} if the name of the target CPU has an @code{el} suffix
+and @code{big} otherwise.
+
Note that these commands merely adjust interpretation of symbolic
data on the host, and that they have absolutely no effect on the
target system.
@code{target} command.
@item target remote @code{@var{host}:@var{port}}
+@itemx target remote @code{@var{[host]}:@var{port}}
@itemx target remote @code{tcp:@var{host}:@var{port}}
+@itemx target remote @code{tcp:@var{[host]}:@var{port}}
+@itemx target remote @code{tcp4:@var{host}:@var{port}}
+@itemx target remote @code{tcp6:@var{host}:@var{port}}
+@itemx target remote @code{tcp6:@var{[host]}:@var{port}}
@itemx target extended-remote @code{@var{host}:@var{port}}
+@itemx target extended-remote @code{@var{[host]}:@var{port}}
@itemx target extended-remote @code{tcp:@var{host}:@var{port}}
+@itemx target extended-remote @code{tcp:@var{[host]}:@var{port}}
+@itemx target extended-remote @code{tcp4:@var{host}:@var{port}}
+@itemx target extended-remote @code{tcp6:@var{host}:@var{port}}
+@itemx target extended-remote @code{tcp6:@var{[host]}:@var{port}}
@cindex @acronym{TCP} port, @code{target remote}
Debug using a @acronym{TCP} connection to @var{port} on @var{host}.
-The @var{host} may be either a host name or a numeric @acronym{IP}
-address; @var{port} must be a decimal number. The @var{host} could be
-the target machine itself, if it is directly connected to the net, or
-it might be a terminal server which in turn has a serial line to the
-target.
+The @var{host} may be either a host name, a numeric @acronym{IPv4}
+address, or a numeric @acronym{IPv6} address (with or without the
+square brackets to separate the address from the port); @var{port}
+must be a decimal number. The @var{host} could be the target machine
+itself, if it is directly connected to the net, or it might be a
+terminal server which in turn has a serial line to the target.
For example, to connect to port 2828 on a terminal server named
@code{manyfarms}:
target remote manyfarms:2828
@end smallexample
+To connect to port 2828 on a terminal server whose address is
+@code{2001:0db8:85a3:0000:0000:8a2e:0370:7334}, you can either use the
+square bracket syntax:
+
+@smallexample
+target remote [2001:0db8:85a3:0000:0000:8a2e:0370:7334]:2828
+@end smallexample
+
+@noindent
+or explicitly specify the @acronym{IPv6} protocol:
+
+@smallexample
+target remote tcp6:2001:0db8:85a3:0000:0000:8a2e:0370:7334:2828
+@end smallexample
+
+This last example may be confusing to the reader, because there is no
+visible separation between the hostname and the port number.
+Therefore, we recommend the user to provide @acronym{IPv6} addresses
+using square brackets for clarity. However, it is important to
+mention that for @value{GDBN} there is no ambiguity: the number after
+the last colon is considered to be the port number.
+
If your remote target is actually running on the same machine as your
debugger session (e.g.@: a simulator for your target running on the
same host), you can omit the hostname. For example, to connect to
Note that the colon is still required here.
@item target remote @code{udp:@var{host}:@var{port}}
+@itemx target remote @code{udp:@var{[host]}:@var{port}}
+@itemx target remote @code{udp4:@var{host}:@var{port}}
+@itemx target remote @code{udp6:@var{[host]}:@var{port}}
+@itemx target extended-remote @code{udp:@var{host}:@var{port}}
@itemx target extended-remote @code{udp:@var{host}:@var{port}}
+@itemx target extended-remote @code{udp:@var{[host]}:@var{port}}
+@itemx target extended-remote @code{udp4:@var{host}:@var{port}}
+@itemx target extended-remote @code{udp6:@var{host}:@var{port}}
+@itemx target extended-remote @code{udp6:@var{[host]}:@var{port}}
@cindex @acronym{UDP} port, @code{target remote}
Debug using @acronym{UDP} packets to @var{port} on @var{host}. For example, to
connect to @acronym{UDP} port 2828 on a terminal server named @code{manyfarms}:
@anchor{set remote hardware-breakpoint-limit}
@item set remote hardware-watchpoint-limit @var{limit}
@itemx set remote hardware-breakpoint-limit @var{limit}
-Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or
-watchpoints. A limit of -1, the default, is treated as unlimited.
+Restrict @value{GDBN} to using @var{limit} remote hardware watchpoints
+or breakpoints. The @var{limit} can be set to 0 to disable hardware
+watchpoints or breakpoints, and @code{unlimited} for unlimited
+watchpoints or breakpoints.
+
+@item show remote hardware-watchpoint-limit
+@itemx show remote hardware-breakpoint-limit
+Show the current limit for the number of hardware watchpoints or
+breakpoints that @value{GDBN} can use.
@cindex limit hardware watchpoints length
@cindex remote target, limit watchpoints length
@anchor{set remote hardware-watchpoint-length-limit}
@item set remote hardware-watchpoint-length-limit @var{limit}
-Restrict @value{GDBN} to using @var{limit} bytes for the maximum length of
-a remote hardware watchpoint. A limit of -1, the default, is treated
-as unlimited.
+Restrict @value{GDBN} to using @var{limit} bytes for the maximum
+length of a remote hardware watchpoint. A @var{limit} of 0 disables
+hardware watchpoints and @code{unlimited} allows watchpoints of any
+length.
@item show remote hardware-watchpoint-length-limit
Show the current limit (in bytes) of the maximum length of
Certain commands to @value{GDBN} may produce large amounts of
information output to the screen. To help you read all of it,
@value{GDBN} pauses and asks you for input at the end of each page of
-output. Type @key{RET} when you want to continue the output, or @kbd{q}
-to discard the remaining output. Also, the screen width setting
-determines when to wrap lines of output. Depending on what is being
-printed, @value{GDBN} tries to break the line at a readable place,
-rather than simply letting it overflow onto the following line.
+output. Type @key{RET} when you want to see one more page of output,
+@kbd{q} to discard the remaining output, or @kbd{c} to continue
+without paging for the rest of the current command. Also, the screen
+width setting determines when to wrap lines of output. Depending on
+what is being printed, @value{GDBN} tries to break the line at a
+readable place, rather than simply letting it overflow onto the
+following line.
Normally @value{GDBN} knows the size of the screen from the terminal
driver software. For example, on Unix @value{GDBN} uses the termcap data base
Turns on or off debugging messages from the FreeBSD LWP debug support.
@item show debug fbsd-lwp
Show the current state of FreeBSD LWP debugging messages.
+@item set debug fbsd-nat
+@cindex FreeBSD native target debug messages
+Turns on or off debugging messages from the FreeBSD native target.
+@item show debug fbsd-nat
+Show the current state of FreeBSD native target debugging messages.
@item set debug frame
@cindex frame debugging info
Turns on or off display of @value{GDBN} frame debugging info. The
@smallexample
-data-disassemble
[ -s @var{start-addr} -e @var{end-addr} ]
+ | [ -a @var{addr} ]
| [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
-- @var{mode}
@end smallexample
is the beginning address (or @code{$pc})
@item @var{end-addr}
is the end address
+@item @var{addr}
+is an address anywhere within (or the name of) the function to
+disassemble. If an address is specified, the whole function
+surrounding that address will be disassembled. If a name is
+specified, the whole function with that name will be disassembled.
@item @var{filename}
is the name of the file to disassemble
@item @var{linenum}
@item exec-run-start-option
Indicates that the @code{-exec-run} command supports the @option{--start}
option (@pxref{GDB/MI Program Execution}).
+@item data-disassemble-a-option
+Indicates that the @code{-data-disassemble} command supports the @option{-a}
+option (@pxref{GDB/MI Data Manipulation}).
@end ftable
@subheading The @code{-list-target-features} Command
Check that the target descriptions dynamically created by @value{GDBN}
equal the descriptions created from XML files found in @var{dir}.
+@anchor{maint check libthread-db}
+@kindex maint check libthread-db
+@item maint check libthread-db
+Run integrity checks on the current inferior's thread debugging
+library. This exercises all @code{libthread_db} functionality used by
+@value{GDBN} on GNU/Linux systems, and by extension also exercises the
+@code{proc_service} functions provided by @value{GDBN} that
+@code{libthread_db} uses. Note that parts of the test may be skipped
+on some platforms when debugging core files.
+
@kindex maint print dummy-frames
@item maint print dummy-frames
Prints the contents of @value{GDBN}'s internal dummy-frame stack.
memory will be used. Setting it to zero disables caching, which will
slow down @value{GDBN} startup, but reduce memory consumption.
+@kindex maint set dwarf unwinders
+@kindex maint show dwarf unwinders
+@item maint set dwarf unwinders
+@itemx maint show dwarf unwinders
+Control use of the DWARF frame unwinders.
+
+@cindex DWARF frame unwinders
+Many targets that support DWARF debugging use @value{GDBN}'s DWARF
+frame unwinders to build the backtrace. Many of these targets will
+also have a second mechanism for building the backtrace for use in
+cases where DWARF information is not available, this second mechanism
+is often an analysis of a function's prologue.
+
+In order to extend testing coverage of the second level stack
+unwinding mechanisms it is helpful to be able to disable the DWARF
+stack unwinders, this can be done with this switch.
+
+In normal use of @value{GDBN} disabling the DWARF unwinders is not
+advisable, there are cases that are better handled through DWARF than
+prologue analysis, and the debug experience is likely to be better
+with the DWARF frame unwinders enabled.
+
+If DWARF frame unwinders are not supported for a particular target
+architecture, then enabling this flag does not cause them to be used.
@kindex maint set profile
@kindex maint show profile
@cindex profiling GDB
@end enumerate
@end table
+@kindex maint set check-libthread-db
+@kindex maint show check-libthread-db
+@item maint set check-libthread-db [on|off]
+@itemx maint show check-libthread-db
+Control whether @value{GDBN} should run integrity checks on inferior
+specific thread debugging libraries as they are loaded. The default
+is not to perform such checks. If any check fails @value{GDBN} will
+unload the library and continue searching for a suitable candidate as
+described in @ref{set libthread-db-search-path}. For more information
+about the tests, see @ref{maint check libthread-db}.
+
@kindex maint space
@cindex memory used by commands
@item maint space @var{value}
it should contain registers @samp{v0} through @samp{v31}, @samp{fpsr},
and @samp{fpcr}.
+The @samp{org.gnu.gdb.aarch64.sve} feature is optional. If present,
+it should contain registers @samp{z0} through @samp{z31}, @samp{p0}
+through @samp{p15}, @samp{ffr} and @samp{vg}.
+
@node ARC Features
@subsection ARC Features
@cindex target descriptions, ARC Features
@format
@c man begin SYNOPSIS gcore
-gcore [-a] [-o @var{filename}] @var{pid}
+gcore [-a] [-o @var{prefix}] @var{pid1} [@var{pid2}...@var{pidN}]
@c man end
@end format
@c man begin DESCRIPTION gcore
-Generate a core dump of a running program with process ID @var{pid}.
-Produced file is equivalent to a kernel produced core file as if the process
-crashed (and if @kbd{ulimit -c} were used to set up an appropriate core dump
-limit). Unlike after a crash, after @command{gcore} the program remains
-running without any change.
+Generate core dumps of one or more running programs with process IDs
+@var{pid1}, @var{pid2}, etc. A core file produced by @command{gcore}
+is equivalent to one produced by the kernel when the process crashes
+(and when @kbd{ulimit -c} was used to set up an appropriate core dump
+limit). However, unlike after a crash, after @command{gcore} finishes
+its job the program remains running without any change.
@c man end
@c man begin OPTIONS gcore
enable @code{dump-excluded-mappings} (@pxref{set
dump-excluded-mappings}).
-@item -o @var{filename}
-The optional argument
-@var{filename} specifies the file name where to put the core dump.
-If not specified, the file name defaults to @file{core.@var{pid}},
-where @var{pid} is the running program process ID.
+@item -o @var{prefix}
+The optional argument @var{prefix} specifies the prefix to be used
+when composing the file names of the core dumps. The file name is
+composed as @file{@var{prefix}.@var{pid}}, where @var{pid} is the
+process ID of the running program being analyzed by @command{gcore}.
+If not specified, @var{prefix} defaults to @var{gcore}.
@end table
@c man end
projects / binutils-gdb.git / blobdiff